Update schema version attribute to generically handle patch versions

[macintoshpie]

context

auc:BuildingSync/@version is currently an enum of specific versions. Problem is, if we want to later create a patch release, an instance document would no longer be considered valid.

E.g. if we have enums 1.0.0, and we want to create a patch, 1.0.1, the 1.0.0 schema will not allow the instance document to include the 1.0.1 version (it didn't exist at the time so there was no enum for it). But in reality the 1.0.0 schema should allow a 1.0.1 document b/c PATCH includes no features and no breaking-changes.

task

• update our current schemas for next release to handle generic PATCH versions

[macintoshpie]

Here's a proposal for two approaches:

Approach 1: Regex

Update the version validation to use xs:pattern like so (e.g. for v2.4 schema)

<xs:attribute name="version" use="required">
        <xs:annotation>
          <xs:documentation>The versions are sorted by official release date (reverse order).  Note that semantic versioning for BuildingSync was reset in 2016.  v2.0.0-legacy is the last official release of the schema before the version reset and is available in the schema repository: https://github.com/BuildingSync/schema/releases/tag/v2.0.0-legacy.  Since then, semantic versioning started at the v0.2.0 release and progresses as expected.</xs:documentation>
        </xs:annotation>
        <xs:simpleType>
          <xs:restriction base="xs:string">
            <xs:pattern value="2\.[0-4]\.{0-9}+"></xs:pattern>
          </xs:restriction>
        </xs:simpleType>
      </xs:attribute>

example validity check

Pros:

• pretty simple to maintain

Cons:

• output not user friendly (just says your versions doesn't match this regex pattern 😨 )
• allows users to provide literally any patch number (even if it doesn't exist)

Approach 2: add more enums

Add enums with x for patch version, e.g. 2.3.x. In the future, with each MINOR release, we only add the minor version with .x (e.g. MAJOR.MINOR.x, do not add MAJOR.MINOR.0 and MAJOR.MINOR.X)

<xs:attribute name="version" use="required">
        <xs:annotation>
          <xs:documentation>The versions are sorted by official release date (reverse order).  Note that semantic versioning for BuildingSync was reset in 2016.  v2.0.0-legacy is the last official release of the schema before the version reset and is available in the schema repository: https://github.com/BuildingSync/schema/releases/tag/v2.0.0-legacy.  Since then, semantic versioning started at the v0.2.0 release and progresses as expected.</xs:documentation>
        </xs:annotation>
        <xs:simpleType>
          <xs:restriction base="xs:string">
            <xs:enumeration value="2.0.0"/>
            <xs:enumeration value="2.0.x"/>
            <xs:enumeration value="2.1.0"/>
            <xs:enumeration value="2.1.x"/>
            <xs:enumeration value="2.2.0"/>
            <xs:enumeration value="2.2.x"/>
            <xs:enumeration value="2.3.0"/>
            <xs:enumeration value="2.3.x"/>
            <xs:enumeration value="2.4.0"/>
            <xs:enumeration value="2.4.x"/>
          </xs:restriction>
        </xs:simpleType>
      </xs:attribute>

example validity check

Pros:

• clear error to users
• guaranteed semantic validity

Cons:

• maybe confusing to users to see x in version
• more enums to maintain?

[macintoshpie]

@nllong @JieXiong9119 @Ryoken @kflemin thoughts?

[Ryoken]

The regex method is simpler, but I like the enum method's explicit nature... despite it looking dirtier and requiring more work I think I am partial to the enum.

[JieXiong9119]

I like the enum method. A bit more work to maintain might just make it easier to maintain.

[macintoshpie]

Versions have been updated for the 2.4 schema, I won't add 3.0 to the 3.0.0 schema since it is still in prerelease.