diff --git a/spec/spec.md b/spec/spec.md index 5b392b0..ec20b2b 100644 --- a/spec/spec.md +++ b/spec/spec.md @@ -696,6 +696,7 @@ This gives rise to two meanings of the word "version" when applied to an ACDC's The JSON Schema for an ACDC may use composition operators (see below). This allows extensibility in schema such that, in some cases, ACDCs with newer Schema versions may be backward (im)compatible with older schema versions. A new schema version, as given by the `$id` field value, is considered backward incompatible with respect to a previous version of a Schema when any instance of an ACDC that validates (in the JSON Schema sense of validation) against the previous version of the Schema may not be guaranteed to validate against the new version. Because any change to the `version` field value results in a different `$id` field value, the backward compatibility rule also applies changes in the `version` field value. To comply with the semantic versioning rules, a backward incompatible Schema shall have a higher major version number in its `version` field value than any backward incompatible version. +One complication with schema versioning arises when an ACDC has Edges. As discussed below in the Edge section, an Edge block may have a Schema, `s` field, which indicates that the ACDC node the edge points to must validate against the schema indicated by the Edge's Schema, `s` field value. Consequently, the version of the Edge's schema `s` field value may differ from the version of the Schema `s` field value in the ACDC node pointed to by that edge. If both schemas validate, then the Edge's schema version is backward compatible with the ACDC's schema version (node pointed to by the Edge). This means the Edge's schema version may have a higher minor version number than the ACDC's schema version (node pointed to by the Edge). If the Edge's schema does not validate against the ACDC node pointed to by the edge, then the Edge's schema is backward incompatible and shall have a higher major version number than the ACDC's schema (node pointed to by the edge). In this latter case, ACDCs issued under the old major version must either be revoked and reissued to comply with the new major version schema, or the Edge's schema must include a `oneOf` composition that accepts either old or new major versions. In general, this would lead to extending that list of `oneOfs` in that Edge's schema field value to include an entry for each major version change. #### Schema availability @@ -1273,7 +1274,7 @@ When an Edge sub-block has only one field, that is, its node, `n` field, i.e., i ##### Schema, `s` field -When present, the Schema `s` field must appear immediately following the node `n` field in the Edge sub-block. The schema, `s` field provides an additional constraint on the far node ACDC. The far node ACDC shall also validate against an Edge block schema, `s` field when present. To clarify, the Validator, after validating that the provided far node ACDC indicated by the node, `n` field satisfies its (the far ACDC's) own Schema, shall also confirm that far node ACDC passes Schema validation with respect to the Edge's `s` field value. This validation is simplified whenever the SAID of the far node ACDC Schema matches the SAID fo the Edge's Schema, `s` field. Then, only one Schema validation has to be performed. When the Schema SAIDs differ, then two Schema validation runs have to be performed. The Edge Schema, `s` field enables a given Issuer of an ACDC to force forward compatibility constraints on old ACDCs to which a new issuance is chained. +When present, the Schema `s` field must appear immediately following the node `n` field in the Edge sub-block. The schema, `s` field provides an additional constraint on the far node ACDC. The far node ACDC shall also validate against an Edge block schema, `s` field when present. To clarify, the Validator, after validating that the provided far node ACDC indicated by the node, `n` field satisfies its (the far ACDC's) own Schema, shall also confirm that far node ACDC passes Schema validation with respect to the Edge's `s` field value. This validation is simplified whenever the SAID of the far node ACDC Schema matches the SAID of the Edge's Schema, `s` field because only one Schema validation has to be performed. However, when the Schema SAIDs differ, two Schema validation runs shall be performed. The Edge Schema, `s` field enables a given Issuer of an ACDC to force forward compatibility constraints (i.e. minor schema version changes) on old ACDCs to which a new issuance is chained without having to add each old minor version to a list of `oneOf` compositions in the Edge's Schema, `s` field value. Major version changes are, by definition backwards breaking, so either the old version ACDC's must be revoked and reissued or the new Edge's schema value must include a `oneOf` composition that includes the old major versions. See the discussion under the Schema section for Schema versioning. ##### Operator, `o` field