Documenting the decision in an ADR

Oct 13, 2025 by leolavanderia.com.br 62 views

Introduction

In the realm of JSON Schema, the $schema keyword plays a crucial role in defining the structure and validation rules for a document. However, there is a subtle aspect of its usage that has sparked debate and confusion. This article aims to clarify the usage of non-canonical identifiers in the $schema keyword, specifically in the context of referencing metaschemas.

What is Unclear?

The question at the heart of this discussion revolves around the legitimacy of using a non-canonical identifier to refer to a metaschema in the $schema keyword. A non-canonical identifier is a URL that does not conform to the standard format specified in the JSON Schema specification. In other words, it is not a URL that can be easily resolved or looked up in a list of known metaschemas.

To illustrate this point, let's consider an example:

{
  "$id": "https://example.com/some_document",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$defs": {
    "my_embedded_metaschema": {
      "$id": "https://example.com/my_embedded_metaschema",
      "$vocabulary": {
        ...
      }
    },
    ...
  }
}

In this example, the document some_document contains an embedded metaschema my_embedded_metaschema. Now, suppose we want to reference this metaschema in another document. Can we use a non-canonical identifier to do so?

{
  "$id": "https://example.com/another_document",
  "$schema": "https://example.com/some_document#/$defs/my_embedded_metaschema",
  ...
}

In this case, the non-canonical identifier https://example.com/some_document#/$defs/my_embedded_metaschema is used to reference the embedded metaschema. While this might seem like a harmless practice, it could potentially lead to issues in certain implementations that rely on the $schema value as a lookup in a list of known metaschemas.

Proposal

Given the potential risks and complexities associated with using non-canonical identifiers in the $schema keyword, it is recommended to explicitly prohibit this practice. This would ensure that the usage of $schema remains consistent and predictable, reducing the likelihood of errors or unexpected behavior.

Do You Think This Work Might Require an Architectural Decision Record (ADR)?

Yes, this work might require an Architectural Decision Record (ADR) due to its significant and noteworthy implications. An ADR would provide a clear and concise documentation of the decision-making process, including the rationale behind prohibiting the use of non-canonical identifiers in the $schema keyword.

Conclusion

In conclusion, the usage of non-canonical identifiers in the $schema keyword is a topic that warrants careful consideration. While it may seem like a minor issue, it has the potential to cause problems in certain implementations. By explicitly prohibiting this practice, we can ensure that the usage of $schema remains consistent and predictable, ultimately leading to a more robust and reliable JSON Schema ecosystem.

Recommendations

Based on the analysis and proposal outlined in this article, the following recommendations are made:

Prohibit the use of non-canonical identifiers in the $schema keyword: This would ensure that the usage of $schema remains consistent and predictable, reducing the likelihood of errors or unexpected behavior.
Document the decision-making process in an Architectural Decision Record (ADR): This would provide a clear and concise documentation of the decision-making process, including the rationale behind prohibiting the use of non-canonical identifiers in the $schema keyword.

Q&A

Q: What is a non-canonical identifier in the context of JSON Schema? A: A non-canonical identifier is a URL that does not conform to the standard format specified in the JSON Schema specification. In other words, it is not a URL that can be easily resolved or looked up in a list of known metaschemas.

Q: Why is the use of non-canonical identifiers in the $schema keyword a concern? A: The use of non-canonical identifiers in the $schema keyword can lead to issues in certain implementations that rely on the $schema value as a lookup in a list of known metaschemas. This can cause problems in terms of validation, error handling, and overall reliability.

Q: Can you provide an example of a non-canonical identifier in the $schema keyword? A: Here is an example:

{
  "$id": "https://example.com/some_document",
  "$schema": "https://example.com/some_document#/$defs/my_embedded_metaschema",
  ...
}

In this example, the non-canonical identifier https://example.com/some_document#/$defs/my_embedded_metaschema is used to reference an embedded metaschema.

Q: Why is it recommended to prohibit the use of non-canonical identifiers in the $schema keyword? A: It is recommended to prohibit the use of non-canonical identifiers in the $schema keyword because it can lead to inconsistencies and errors in the validation process. By prohibiting this practice, we can ensure that the usage of $schema remains consistent and predictable.

Q: What is an Architectural Decision Record (ADR)? A: An Architectural Decision Record (ADR) is a document that provides a clear and concise documentation of the decision-making process, including the rationale behind a particular decision. In this case, an ADR would be used to document the decision to prohibit the use of non-canonical identifiers in the $schema keyword.

Q: Why is an ADR necessary in this case? A: An ADR is necessary in this case because the decision to prohibit the use of non-canonical identifiers in the $schema keyword has significant and noteworthy implications. An ADR would provide a clear and concise documentation of the decision-making process, including the rationale behind the decision.

Q: What are the benefits of prohibiting the use of non-canonical identifiers in the $schema keyword? A: The benefits of prohibiting the use of non-canonical identifiers in the $schema keyword include:

Improved consistency: By prohibiting the use of non-canonical identifiers, we can ensure that the usage of $schema remains consistent and predictable.
Reduced errors: By prohibiting the use of non-canonical identifiers, we can reduce the likelihood of errors and inconsistencies in the validation process.
Improved reliability: By prohibiting the use of non-canonical identifiers, we can improve the overall reliability of the JSON Schema specification.

Q: What are the next steps in implementing this decision? A: The next steps in implementing this decision include:

Documenting the decision in an ADR: This would provide a clear and concise documentation of the decision-making process, including the rationale behind the decision.
Updating the JSON Schema specification: This would involve updating the specification to prohibit the use of non-canonical identifiers in the $schema keyword.
Communicating the decision to the community: This would involve communicating the decision to the JSON Schema community, including developers, users, and implementers.