gedcom-registries discussion

[dthaler]

• Currently gedcom-registries is only mentioned on the Community page, not Tools or Guides or Specifications. This seems like a gap... perhaps Tools is most appropriate?
• Currently the registry path puts all structure YAML files in the same directory, regardless of version. Of course only v7 URIs exist currently, but there could be v7.1 or v8 URIs in the future, which would need separate files (e.g., because of different superstructure lists or substructure lists). Also there could be v5.5.1 extension structures that one wants to register now as well. Shouldn't we create a directory structure, e.g., by version?

[tychonievich]

On the second item, I'm hesitant to use paths for versions for the following reasons:

• Where do we put files that apply in multiple versions?
• If paths are used for versions it becomes difficult to re-structure the repo later

On the other hand, we will need different files for different versions, for example the 8.0 EXID is scheduled to change in a backwards-incompatible way and 7.1 could add new substructures to 7.0 structures. Subdirectories might be the easiest way to make those files have unique names.

I'd prefer to add some kind of versions flag inside the YAML itself, but have not settled on how I think that should be done. For example, we could do

versions:
  - "5.5.1"
  - "7.0"

or

from-version: "5.3"
removed-from-version: "8.0"

but that might not be ideal. For example, we could record changes in a single YAML file, so e.g. we could have EXID's file have something like

substructures:
  "https://gedcom.io/terms/v7/EXID-TYPE": "{0:1}"

changes:
  - version: "8.0"
    substructures:
      "https://gedcom.io/terms/v7/EXID-TYPE": "{1:1}"

[dthaler]

Regarding version numbering...

The use case is to support registering third-party extensions to motivate features meeting the "awaiting use" criteria, even if the extension was only for 5.5.1 so far because the app hasn't yet supported 7.0.

For validation purposes there should be a way to match the GEDC.VERS value against some list or range in the yaml file.

The 7.0 spec says:

The version number of the official specification that this document’s data conforms to. This must include the major and minor version (for example, “7.0”); it may include the patch as well (for example, “7.0.1”), but doing so is not required.

So the same yaml file for 7.0.x should work in 7.0.y.
But for 5.5.* this was not true. 5.5.1 has things that were not in 5.5 and vice versa (see https://gedcom.io/specifications/ged551.pdf "Modifications in Version 5.5.1" which include both things added and things removed).

[dthaler]

Another point to discuss... YAML files are being generated off the spec today for the standard ones. However if we want them to have from-version: "5.3" etc. then that would not be possible without additional input. Having separate directories instead would allow using the existing tooling to auto-generate the ones for 7.0 and later.

Luther asked:

Where do we put files that apply in multiple versions?

They would appear in the directory for each relevant version.

If paths are used for versions it becomes difficult to re-structure the repo later

Maybe, maybe not. First, we don't have an issue that I know of that would require restructuring the repo. Second, even if restructured, the repo could contain both the old and the new structure in parallel or even in different branches or repos. So I don't see that as a blocker.

[dthaler]

For third party extensions, getting them registered is a challenge. So what do we do if an application's extensions are registered for 7.0 and then it supports 7.1? By the rules of 7.0's SemVer then they should by default apply to 7.1 as well. But there might be things added that would result in some change like

7.0: "https://gedcom.io/terms/v7/EXID-TYPE": "{0:1}"
7.1: "https://gedcom.io/terms/v7/EXID-TYPE": "{0:M}"

Perhaps a minor release by default inherits the files from the previous one, and only deltas require their own file?

[dthaler]

Discussion May 2, 2024 in the GEDCOM Steering Committee meeting:

• A better example is the list of substructures being changed
• Would we require a new extension URL for any breaking change? Section 1.2 implies yes we have to. Is it just for standards or also extensions? We need to think about this some more.
• If an extension appears as a substructure of a given superstructure identified by URI, then does the version matter? Or is the URI sufficient? So maybe the version only matters for extension records?

[dthaler]

Example discussed 9 MAY 2024:
Extension allows _FOO under an INDI-record in 7.0. When the application that defined the extension updates their app to support 7.1, they decide to also allow DATE under _FOO where they didn't before, so the list of substructures changes. This requires an updated YAML, but does the URI change or not?

We think we would recommend:
If they don't export to 7.0 then they use a new URI for the 7.1 variant.
If they export to 7.0 with DATE then they update the same YAML file without a new URI.

For standards, the committee has stricter control and can guarantee the URIs would change in any minor or major change. The spec says that the structure type defines its (standard) substructures.

[dthaler]

For documented extensions, the GEDCOM version seems to be irrelevant as it could be used in any GEDCOM version that supports the superstructures/substructures referenced in the YAML file.