Consider writing a technical RFC for the standard and then make that the SSOT

[mrshll1001]

Lorem uspsm

[mariongalley]

That's so radical!

[mrshll1001]

dskdhsakdhksa

[mrshll1001]

So I stumbled across this when doing a quick issue review and got really confused about the comments. I believe that the previous comments were the result of using this issue as a demo during a Github demonstration to the SC.

In any case, I think this is a thing worth considering either to do or else to consciously dismiss in favour of our current approach.

Our current approach is to use the schema and codelists as the SSOT for the standard. This has a range of benefits. It benefits from tight version control as a technical artefact, which can then be used to validate data and generate reference materials from it e.g. the schema tables and codelist tables from the docs. It can also be used to generate other serialisations of the data via flatten-tool.

However, technologies rise and fall. JSON Schema looks like it will be around for a while but it will not be around forever. This might cause issues if we want to change the implementation technology for the schema but not perform a MAJOR upgrade. There are also questions as to what occurs if we want to enact a JSON Schema version upgrade going e.g. from Draft 4 to Draft 2020-12; does that constitute a PATCH? A MAJOR change? No change?

If we wanted to, we could write a technical document defining the standard in RFC-style language. For the uninitiated, RFCs are a form of technical document which specify protocols, standards, etc. Some reference RFCs:

• RFC 3339 – outlines datetime standard formats (mostly compatible with ISO 8601)
• RFC 1176 – which outlines the IMAP protocol used for email clients
• RFC 2119 – defines the usage of terms MUST, SHOULD, etc. It is often referenced in other RFCs which want to make use of these terms.

… and so forth.

What got me thinking about this, though, is ActivityPub and ActivityStreams. Technically these are not defined in RFCs but they are defined in versioned documents and use RFC style language.

• ActivityPub
• ActivityStreams

These define objects and semantics and rules in a technical document that is agnostic to implementation technology such as schemas, but in a way that is unambiguous. From the ActivityStreams document:

This specification describes a JSON-based [RFC7159] serialization syntax for the Activity Vocabulary that conforms to a subset of [JSON-LD] syntax constraints but does not require JSON-LD processing. While other serialization forms are possible, such alternatives are not discussed by this document.

Through this we know:

• that the data is JSON (defined by an RFC)
• specifically conforms to a subset of JSON-LD (defined by a reference)
• and uses the Activity Vocabulary syntax (also referenced)

The document also uses the language specified in RFC 2119 to define rules:

All properties with date and time values MUST conform to the "date-time" production in [RFC3339] with the one exception that seconds MAY be omitted. An uppercase "T" character MUST be used to separate date and time, and an uppercase "Z" character MUST be used in the absence of a numeric time zone offset.

Through the combination of defined language and references to RFCs and other technical documents, the document builds a comprehensive and normative definition of what constitutes valid ActivityStreams data.

This means that I think it is reasonable to define the 360Giving standard in terms of a technical document rather than a schema. This allows us a degree of separation between the definition of the standard, and the schema which then manifests or embodies the rules of the standard. This allows us to swap out the schema with other technology as the need arises, or upgrade the version of the technology as needed without triggering a standard upgrade process.

I do think there are (at least) several considerable drawbacks from a practical standpoint:

• It's not an inconsiderable ask to write this style of document. It needs to be written carefully and carefully edited.
• We'd need to decide how to version this document. Does the document itself update with a new version number, or do we issue a new document defining each version of the standard?
• If we do a standard upgrade we need to write it in this technical document, change the version appropriately, and then also do the needful on the schema. This might double (or triple, in practice) our effort for not much benefit for MINOR upgrades.
• How do PATCH upgrades work? If the bug is in the schema vs an oversight in the technical document?
• How do proposal documents look in this world? Do they need to change? What work needs to be done to bring the SC along through this document.

Conclusion: I think this style of standardisation is quite powerful and flexible, but we need to consider it carefully. It may be that we are happy with the current approach we have, but it's worthwhile explicity deciding on that and writing this down somewhere so we can reference our justification.