Skip to content

v3.2: Decide on names of new Example Object fields #4658

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
handrews opened this issue Jun 5, 2025 · 1 comment
Open

v3.2: Decide on names of new Example Object fields #4658

handrews opened this issue Jun 5, 2025 · 1 comment
Labels
example obj/keywords Issues with the Example Object or exampel(s) keywords
Milestone

Comments

@handrews
Copy link
Member

handrews commented Jun 5, 2025

PR #4647 adds four new fields to the Example Object. There seems to be consensus that we should add the fields once that PR is out of draft, but there is less consensus on the names.

In this issue, "JSON/YAML" refers to JSON (as specified by the RFC) and the subset of YAML that we allow for OAD authoring. This subset is intended to be essentially equivalent to JSON, as all OAD keys and values MUST be possible to write in JSON.

The names in the PR are:

  • dataValue: An inline example value of the data structure that is validated by a Schema Object, possibly trivially if the data is raw binary as that is outside of JSON Schema's standard data model
  • externalDataValue: Like dataValue but for values not possible to inline in JSON/YAML, such as a raw binary image or video
  • serializedValue: An inline example of the fully serialized value, which MUST be a string
  • externalSerializedValue: Like serializedValue but for values not possible to inline as a JSON/YAML string.

@mikekistler has questioned "data" and brought up that JSON Schema uses "instance." My feeling is that "instance" is too jargon-y, and the data is not necessarily a proper JSON Schema instance when binary data is involved, but I could be convinced to go with it if I'm in the minority here.

@handrews handrews added this to the v3.2.0 milestone Jun 5, 2025
@handrews handrews added the example obj/keywords Issues with the Example Object or exampel(s) keywords label Jun 5, 2025
@handrews
Copy link
Member Author

handrews commented Jun 6, 2025

BTW I do not care what the names are. Just lmk when there's consensus and I'm happy to write a PR to update the text with the final names. I have just separated this out (and made it a 3.2 release blocker) so that PRs #4647 and #4648 do not get held up on naming debates.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
example obj/keywords Issues with the Example Object or exampel(s) keywords
Projects
None yet
Development

No branches or pull requests

1 participant