Enumerate key architectural principles

[handrews]

There are some underlying principles that the JSON Schema project has been based on, but we've never really written them out. A concise list would be appropriate in the Core spec, as they might head off a few questions.

They also provide some general guidance on how to design keywords for extension vocabularies.

• JSON Schema works with all possible instance resources that can be parsed into its data mode, including all syntactically legal JSON documents with well-defined behavior per RFC 8259†. No aspect of the instance data's structure or contents is constrained.
• It is possible (and RECOMMENDED?) to resolve all URI references (e.g. $id, $ref, and $recursiveRef) and locate all defined fragments ($anchor) used in JSON Schema functionality just from the schemas, without an instance.
• The result of applying a schema object to an instance is a function only of the schema object and its dynamic-scope subschemas. Assuming URI references were already resolved, it is never necessary to know the context (parent schema) of the schema object.
• Keywords SHOULD be independent, but MAY be defined in terms of the assertion and/or annotation results of other keywords within the same schema object.
• Keywords behavior fits into one or more classifications, but MUST have the same classification(s) regardless of its value.††

†Note that a JSON object with duplicate property names is syntactically legal but does not have well-defined behavior per RFC 8259. There are also limits on floating point interoperability.

††this is why we split dependencies which changed classification depending on whether it was an object of schemas or an object of string arrays.

Are there any other such principles? I don't think I want to include general principles like "least power", just the ones that couldn't be found anywhere else but within JSON Schema.

[gregsdennis]

I think something about it being a constraint-based system, and as a result, concepts like inheritance do not fit well.

[Relequestual]

I feel like we should say something about Meta-Data Annotations and the semantic meaning of such keywords, but I'm not sure what... I know that's not directly helpful but it might spark some other thoughts.

[handrews]

Everything in JSON Schema is addressed using URI-references (including full URIs) or Relative JSON Pointer. Those are the two things that we use today (URIs everywhere, Relative JSON pointer in Hyper-Schema).

This principle would have flushed out problems with OpenAPI's discriminator keyword, which addresses schemas by their name in the definitions (OAS2) or components (OAS3) structure.

[handrews]

Also, JSON Schema does not include anything about performing I/O to fetch schemas or other resources. This will get addressed in detail through json-schema-org/json-schema-spec#849. But it's worth calling out. JSON Schema specifies how to handle schemas and instances that have been parsed and loaded into memory (or are being processed as a stream, or whatever). It does not specify how things get parsed and loaded. json-schema-org/json-schema-spec#849 is really about clarifying that boundary.

[Relequestual]

@handrews Given you expressed wanting to bump this issue, I'll migreate it to the website repo. I think this would fit on an "implementation advice" page or similar.

[benjagm]

is this suitable content for the new For implementers section? @Julian @Relequestual

[Julian]

They seem like they should be evaluated/agreed upon to see if all the people writing the spec indeed think they're true guiding principles -- but otherwise to me yeah I think so!

[github-actions[bot]]

Hello! :wave:

This issue has been automatically marked as stale due to inactivity :sleeping:

It will be closed in 180 days if no further activity occurs. To keep it active, please add a comment with more details.

There can be many reasons why a specific issue has no activity. The most probable cause is a lack of time, not a lack of interest.

Let us figure out together how to push this issue forward. Connect with us through our slack channel : https://json-schema.org/slack

Thank you for your patience :heart: