Listing superstructures of relocated standard structures

[dthaler]

https://gedcom.io/terms/format has a "superstructures" section per structure. However a relocated standard structure is supposed to have the same URI as the standard structure, so an extension that has a relocated standard structure can't have a different YAML file.

Should the standard YAML file be updated for each extension that relocates it? Or is there no way to specify the "superstructures" section, and only rely on the "substructures" section of the extension structure it's relocated under?

[tychonievich]

In https://gedcom.io/terms/format we have:

Because new structures may be added over time in any order, x may be a substructure of y if either x’s superstructures includes y or y’s substructures includes x.

We have superstructures to allow extensions to be substructures of standard structures. We have substructures to allow extensions to be superstructures of standard structures. For example, an extension individual event would have g7:record-INDI in its superstructures and g7:DATE in its substructures, but presumably not have either of the matching entries in the standard structure's YAML.

The YAML format has similar facilities for enumerations (an extension set can include standard values with enumeration values, and extension values can be placed in standard sets with value of).

I think that relocated standard structures will usually not needed under extensions; there the "extension-defined substructures" should cover most cases, or at least that was the intent: we may have missed some case. But I do think the relocated standard structure idea might need revisiting. By definition they violate normal sub/super rules, but they don't indicate new rules (making validation impossible) and there's currently no way to give similar freedom to extension structures.

[tychonievich]

Put another way:

X may be a substructure of Y if any of the following apply:

• X's YAML file has superstructures entry with key Y
• Y's YAML file has substructures entry with key X
• X is a relocated standard structure (extension tag and standard URI)

[dthaler]

Put another way:

X may be a substructure of Y if any of the following apply:

• X's YAML file has superstructures entry with key Y
• Y's YAML file has substructures entry with key X
• X is a relocated standard structure (extension tag and standard URI)

Or

• X is an undocumented extension structure
• Y is an undocumented extension structure

Correct?

[dthaler]

@tychonievich https://[gedcom.io/testfiles/gedcom70/extension-record.ged](https://gedcom.io/testfiles/gedcom70/extension-record.ged) has:

0 @LOC1@ _LOC
1 NAME Town
2 DATE FROM 1800 TO 1900

So I think it's actually more complicated since that example (DATE under NAME) is permitted in the spec:

_LOC.NAME and _LOC.NAME.DATE are both extension-defined substructures. Their meaning is defined by the specification defining _LOC.

So I think it's also:

• Y is somewhere (any number of levels deep) beneath an extension structure

Correct? I think it would be help to explicitly state this set of conditions somewhere.

[tychonievich]

Hm, I think that example needs to be changed. I can't find a way for it to work with a documented extension. If we had

extension tags: [_LOC]
substructures:
    "https://gedcom.io/terms/v7/NAME": "{0:1}"

then it would be a g7:NAME which does not have a DATE substructure. On the other hand, if we had instead

extension tags: [_LOC]
substructures:
    "https://example.com/LocationName": "{0:1}"

then the name should use an extension tag because it's not a standard structure type.

[tychonievich]

Here's an effort to list all the cases covered by the current spec:

---

:::note

This specification allows structures to appear in the following contexts:

• Standard

  • tag: stdTag
  • URI: Defined in this specification.
  • placement: In a context and with a cardinality defined in this specification.

• Relocated

  • tag: extTag
  • URI: Given in the schema as the URI of a structure type defined in this specification.
  • placement: only in a context where this specification does not list it, and only if its meaning makes sense in that content.

• Aliased

  • tag: extTag
  • URI: Given in the schema as the URI of a structure type defined in this specification.
  • placement: In a location where this specification allows it. Note that aliased structures should never be intentionally added to a file, but might end up in one if an extension is made standard in a subsequent minor version of the specification.

• Undocumented Extension

  • tag: extTag
  • URI: None, because this tag is not defined in the schema.
  • placement: Anywhere, with any cardinality. If the application believes it knows what the undocumented extension means it may edit it, but should replace it with a documented, registered extension to facilitate interoperability with other applications.

• Unrecognized Extension

  • tag: extTag
  • URI: Given in the schema, but not understood by the application.
  • placement: Anywhere, with any cardinality; however, applications should treat these as read-only, not editing or adding them.

• Unrecognized Extension-Defined

  • tag: stdTag
  • URI: One of the URIs of structures defined in this specification with this tag.

  • placement: As a substructure of an undocumented extension, an unrecognized extension, or another unrecognized extension-defined structure.

    (maybe add?) an unrecognized extension-defined structure's set of unrecognized extension-defined substructures (and their unrecognized extension-defined substructures transitively) must be consistent with at least one standard structure with this tag. For example, there are five standard structures with tag DATE; three have a PHRASE substructure so an unrecognized extension-defined DATE structure may have a PHRASE substructure, but none have a NOTE substructure so an unrecognized extension-defined DATE structure may not have a NOTE substructure (but may have a g7:NOTE as a relocated substructure).

• Documented Extension

  • tag: extTag
  • URI: given in the schema and understood by the application, likely by consulting the GEDCOM registries.
  • placement: As defined in the documentation. A registry-defined structure is permitted as a record if its superstructures entry is {}; it is permitted as a substructure of structure type X if either X appears in its substructures entry or it appears in X's superstructure's entry.

• Documented Extension-Defined

  • tag: stdTag
  • URI: One of the URIs of structures defined in this specification with this tag; which one is defined by the superstructure, likely in the GEDCOM registries.
  • placement: As a substructure of a documented extension or another documented extension-defined structure. A registry-defined superstructure can permit a documented extension-defined substructure by including the URI of a standard structure type in its substructures entry. A documented extension-defined superstructure permits as documented extension-defined substructures any structure that structure type may have as defined in this specification.

:::

[dthaler]

Hm, I think that example needs to be changed. I can't find a way for it to work with a documented extension.

I agree, I would prefer that that example not be valid. However, changing it at this point would seem to be a breaking change where an existing valid GEDCOM 7.0 file would become invalid, so wouldn't that change have to wait for next-major?

[dthaler]

Discussion 11/16/2023:

• We don't want to invalidate how existing apps use _LOC today
• There may be ways to let YAML files specify deep structure organization
  • Either have the type of substructures be cardinality OR map, or
  • Add some other key that contains hierarchical information

[dthaler]

Discussion January 4, 2024:

• Example in spec put a standard tag (NAME) where it cannot be a g7:NAME or any other standard URI but must be an extension URI due to the DATE substructure.
• We could deprecate the use of standard tags in extension-defined substructures when they are not identical to the standard definition, but we cannot disallow them as that would be a breaking change.
• We don't need to allow a way for the YAML to specify such a deprecated use.
• Current YAML syntax does not yet have a way to specify stdTag as an extension, we need a way to allow that in order to support the current example in the spec.
• We can revisit the discussion in the future if new information is found while implementing in the future.