Improve external vocabulary references

[maximiliani]

This PR introduces a new model for external vocabulary referencing introduced in #35.
It also introduces a new "Extensions" section that currently contains external vocabulary referencing and Inline/Lambda FDOs.
The reason for introducing an extensions section is (see also #35) that some features that are not essential to the functioning of FDOs can be supported by clients, but are not mandatory.

This PR closes #35.

This PR is based on the changes made in #50.

[github-actions]

🚀 PR Preview Available

A preview deployment of this PR is now available.

🔗 Preview URL: https://fairdo-org.github.io/fdo-architecture-spec/preview/pr-59/

⚠️ This preview is automatically updated with each commit. The banner on the preview page will show when the PR is merged or closed.

[Copilot]

Pull request overview

This PR adds optional extensions for inline FDOs and external vocabulary references, relocates terminology to the appendix, and updates specification structure and numbering.

Changes:

• Adds inline-FDO and external-vocabulary extension rules.
• Moves the glossary and introduces an attribute-definitions appendix heading.
• Updates metadata, references, rule identifiers, tables, and editorial wording.

Reviewed changes

Copilot reviewed 26 out of 30 changed files in this pull request and generated 16 comments.

Show a summary per file

File	Summary
sections/05_appendix/02_AttributeDefs.html	Adds the appendix heading; the referenced attribute list remains empty. Moderate (2 votes).
sections/05_appendix/01-Terminology.html	Fix missing spaces before linked terms and in ActiveFDO. Nits (3, 3, and 2 votes).
sections/02_fdo-processing-block/Step9.html	Updates evaluation wording.
sections/02_fdo-processing-block/Step8.html	Formats the NORULES status.
sections/02_fdo-processing-block/Step6.html	Corrects profile inspection wording and table markup.
sections/02_fdo-processing-block/Step5.html	Corrects inspection wording and table markup.
sections/02_fdo-processing-block/Step4.html	Updates validation wording and table numbering.
sections/02_fdo-processing-block/Step3.html	Add whitespace before the linked FDO term. Nit (3 votes).
sections/02_fdo-processing-block/Step2.html	Fixes terminology and paragraph markup.
sections/02_fdo-processing-block/Step1.html	Fixes example-list markup and wording.
sections/02_fdo-processing-block/Introduction.html	Refines the processing introduction prose.
sections/01_fdo-building-block/12-Updating.html	Renumbers updating rules and fixes markup.
sections/01_fdo-building-block/11-FDO-Types.html	Renumbers type and operation rules.
sections/01_fdo-building-block/10-Mandatory-Attributes.html	Renumbers mandatory-attribute rules.
sections/01_fdo-building-block/09-Validation.html	Renumbers and refines validation rules.
sections/01_fdo-building-block/08-Extensions.html	Adds extension specifications. Findings include four moderate issues for broken fragments and mandatory vocabulary metadata, five editorial nits, and one critical issue requiring safe $TERM$ parameter binding and execution restrictions.
sections/01_fdo-building-block/07-Referencing.html	Moves inline and vocabulary-reference content.
sections/01_fdo-building-block/06-Syntax-Def.html	Updates syntax terminology and table numbering.
sections/01_fdo-building-block/05-Attributes.html	Direct vocabulary references to #extensions rather than #advanced-ref. Nit (3 votes).
sections/01_fdo-building-block/04-FDO-Profiles.html	Correct the profile requirement wording. Nit (2 votes). Renumber duplicate [R4-1] references to [R4-2]. Moderate (2 votes).
sections/01_fdo-building-block/03-FDO-Records.html	Updates the data attribute definition.
sections/01_fdo-building-block/02-Granularity.html	Refines the section definition.
sections/01_fdo-building-block/01-PID.html	Add the missing space in “The PID system.” Nit (3 votes).
sections/00_introduction/03-Terminology.html	Removes the former terminology section.
sections/00_introduction/02-High-Level-Overview.html	Updates terminology and registry wording.
sections/00_introduction/00-Intro.html	Refines the FDO definition.
index.html	Updates metadata, section ordering, and appendix includes.

Suppressed comments (10)

index.html:214

• Adding data-lt="FDO type system" makes “FDO type system” an alias for the entire “FDO Building Blocks” heading. Those concepts are not equivalent—the section also covers PID, granularity, data, extensions, and updating—so references such as the one in 05-Attributes.html resolve to the wrong definition. Define the type-system term in the FDO Types section instead of aliasing it here.

      <h2><dfn data-lt="FDO type system">FDO Building Blocks</dfn></h2>

sections/00_introduction/02-High-Level-Overview.html:149

• DTR and data type registry are being defined as aliases for the generic phrase “open registries,” but a DTR is a specific registry and the following sentences distinguish forum registries from community registries. This causes DTR references to resolve to the wrong concept; define the specific Data Type Registry separately from the generic open-registry requirement.

        <strong>Registries</strong>: <a>Attribute Definitions</a> and profiles must be stored in <dfn data-lt="DTR|data type registry">open registries</dfn>.

sections/01_fdo-building-block/05-Attributes.html:17

• This edited tuple description drops the space before the linked attribute definition and uses “Latter” without an antecedent article. The rendered requirement should read “an attribute definition” and “The latter”.

                The first element of the tuple MUST be either a <a>PID</a> that resolves to an<a>attribute definition</a>
                or a human-readable name of an <a>attribute</a>.
                Latter MAY result in ambiguities (e.g., due to naming conflicts) and MAY NOT support certain mechanisms in this document;

sections/01_fdo-building-block/08-Extensions.html:17

• The new section first states that these features are not essential and are optional, but then calls external vocabulary reuse “essential for FDOs.” This gives contradictory normative guidance; describe the capability as useful or optional rather than essential.

    It is essential for <a>FDOs</a> that existing vocabularies, ontologies, and terminologies can be reused in <a>FDO records</a>
    (even if they do not fulfill the same guarantees as <a>attribute definitions</a>).
    Using a vocabulary term as an <a>attribute</a> in an <a>FDO record</a> similar to an <a>attribute definition</a> is explicitly supported as a <a>community attribute</a>.

sections/01_fdo-building-block/08-Extensions.html:33

• R8-2 requires an ImportVocabulary tuple but does not normatively declare that the 0.FDO/ImportVocabulary definition uses ExternalVocabularyReference; that behavior appears only in the informative example below. Without the declaration, a client cannot know that importing a vocabulary enables the term-level checks described here. State this mechanism in the normative rule or attribute definition.

        To use external vocabulary terms as <a>attribute definitions</a> in an <a>FDO record</a>, the record MUST contain the <em><a>0.FDO/ImportVocabulary</a></em> <a>attribute</a>.
        Values of the <em><a>0.FDO/ImportVocabulary</a></em> <a>attribute</a> MUST refer to an <a>FDO</a> that follows the <a>profile definition</a> <a><em>0.FDO/VocabularyDef</em></a>.

sections/01_fdo-building-block/08-Extensions.html:33

• Issue #35 names the registry attribute 0.FDO/ImportsVocabulary, but this rule and the examples use 0.FDO/ImportVocabulary. These are different identifiers, so implementations could register and emit incompatible attributes; choose one spelling and update every occurrence and example consistently.

    <dt><h4 class="rule-heading" id="rule-r8_2">[R8-2] <dfn data-lt="0.FDO/ImportVocabulary">Declaration of External Vocabulary Usage in an <a>FDO record</a></h4></dt>
    <dd>
        To use external vocabulary terms as <a>attribute definitions</a> in an <a>FDO record</a>, the record MUST contain the <em><a>0.FDO/ImportVocabulary</a></em> <a>attribute</a>.
        Values of the <em><a>0.FDO/ImportVocabulary</a></em> <a>attribute</a> MUST refer to an <a>FDO</a> that follows the <a>profile definition</a> <a><em>0.FDO/VocabularyDef</em></a>.

sections/01_fdo-building-block/08-Extensions.html:69

• 0.FDO/ImportVocabulary is described as accepting a profile reference, but the example says its validation mechanism is ExternalVocabularyReference. The profile-referencing rules use ProfileReference for values that must resolve to a FDO conforming to a profile; using the mechanism shown here does not express the required VocabularyDef target.

            The <a>attribute definition</a> <a><em>0.FDO/ImportVocabulary</em></a> states that it uses external <a>attribute</a> referencing through the
            <a>attribute</a> <em>(<a><em>0.FDO/ValidationMechanism</em></a>, ExternalVocabularyReference)</em>.
            It accepts <a>profile references</a> to <a>FDOs</a> that follow the <a>profile definition</a> <a><em>0.FDO/VocabularyDef</em></a>.

sections/01_fdo-building-block/08-Extensions.html:97

• This link has the same missing # fragment marker, and it points to R8-3 even though the paragraph describes an attribute definition applying external vocabulary referencing, which is specified by R8-1. Link it to the in-document R8-1 requirement.

        <a>External vocabulary referencing</a> can also be used to reference a term from an external vocabulary as the value of an <a>attribute</a> (see <a href="rule-r8_3"></a>).

sections/05_appendix/01-Terminology.html:54

• This moved glossary text renders “dataFDOs” without whitespace. Add a space before the link.

        are not data<a>FDOs</a>.

sections/05_appendix/01-Terminology.html:136

• The glossary heading is an <a> link, but this item no longer defines the singular term “Persistent Identifier”; the nested definition only advertises PID and persistent identifiers. Add the singular label to data-lt or make the heading itself the definition so ReSpec can resolve this term consistently.

        <b><a>Persistent Identifier</a></b>:
        Every <a>FDO</a> is assigned one or more <dfn data-abbr="PID" data-lt="PID|persistent identifiers">globally unique, persistent, and resolvable identifier</dfn>.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Pfeil]

I was not able to do a deep review in one session, so I focussed on the conceptual level for now, starting with the examples. Deeper review will come later.

[Pfeil]

The outgoing arrow line is likely meant to start at the center of 0.FDO/ImportVocabulary, I assume. Should be a capital C, I think. Occurs multiple times in this image as well as in the other image.

[Pfeil]

How do I differentiate this case from the other example?

In other words:
As both cases are basically structured the same, I conclude that all imported terms in both examples can be used as both, keys and values in a record.

Is that correct? Or is there a difference? Is it intended?

I think the only thing differentiating them is the 0.FDO/ImportVocabulary. I assume it is intended that this term is special (importing terms as keys), but all other attributes import vocabularies as values?

[Pfeil]

Here some comments.

One side note in addition: I took your drawings and sketched around a bit. The result is that we could use 0.FDO/Profile as a mechanism to import terms as attributes if we make this a special profile feature, which removed the need for the 0.FDO/ImportVocabulary term and might help to remove the redundant meaning from the special ValidationMechanism. Not sure if I oversee something.

[Pfeil]

If it is essential, then why is it an extension? Proposal:

"In some cases, it will be useful to reuse existing ... . For example, existing, specific metadata could be added this way."

[Pfeil]

I think we should write more about how exactly this influences validation. What "feature" is meant here? How shall I expect the value? Unfortunately I fail to propose something, because I can't derive it. Maybe we need a small session on this to discuss this.

My feeling is:

• this mechanism actually allows all values (no regex-style validation or assertions on the value)
• In the examples the values are both, PIDs or terms from the vocabulary, so there is actually no real validation or other assertions in place.
• The meaning is that "if the value is resolvable and a vocab definition, import and allow the prefix".

[Pfeil]

I suggest (in additon to fixing the typo), that we start by a table showing the attributes which are currently introduced in the text, that make this record special. We have such tables also in other places. We should start with the table and add with text some context for single attributes etc. I think this will make the text easier to write and read.

[Pfeil]

I added such a table and cleant the text. Please feel free to improve or revert :)

[Pfeil]

DownloadURL can be mentioned if we defined it, but actually it would not need to be a http GET, so should we refer to 0.FDO/Data?

[Pfeil]

Did you check if this is how sparql works? The query could also return one result with the term if ok or so.

[Copilot]

🟡 Changes recommended

Unresolved normative inconsistencies, missing definitions, broken references, and a query-safety issue block approval.

Get a fresh assessment by requesting another Copilot review.

Review details

Suppressed comments (14)

index.html:176

• All existing localBiblio entries in this configuration use href, which is the field ReSpec uses for the bibliography link. Using url here can leave [[!RDA-DTR-WG]] unresolved or unlinked.

            url: "https://zenodo.org/records/1406127"

sections/00_introduction/02-High-Level-Overview.html:53

• R1-3 now permits a PID record to be arbitrary and not provide an FDO, so this unqualified MUST is broader than the PID model and contradicts that exception. Scope the statement to a PID that identifies an FDO, or remove the non-FDO PID-record case.

        A <a>PID system</a> MUST resolve the <a>PID</a> to an <a>FDO record</a>.

sections/01_fdo-building-block/01-PID.html:21

• The new definition allows a resolved PID record to contain arbitrary content that does not provide an FDO, but the overview and processing pipeline require a PID used for an FDO to resolve to an FDO record. Scope this case to non-FDO PID records or define how clients distinguish and handle it; otherwise S-3 cannot satisfy its FDO-record input/output contract.

        A <a>PID record</a> is an at least <a>machine readable</a> structure sent back when resolving a <a>PID</a>.
        A subset of the <a>PID record</a> MAY contain the <a>FDO record</a>, refer to the <a>FDO record</a>, or refer to another <a>PID</a>.
        The contents of a <a>PID record</a> can also be arbitrary, in which case, depending on the <a>implementation</a>, it does not provide an <a>FDO</a>.

sections/01_fdo-building-block/02-Granularity.html:47

• These edits introduce nested <a> elements, producing invalid link markup and potentially confusing ReSpec's autolinking. The inner anchors are sufficient; do not wrap them in another <a>.

        Every <a>FDO attribute</a> in an <a>FDO record</a> only describes the identified <a>resource</a> and not any other <a><a>resources</a></a>.
        Even if the <a>FDO</a> is a <a>collection</a>, all <a>attributes</a> in the <a>FDO record</a> describe the<a><a>resource</a></a> as a whole and parts of it.

sections/01_fdo-building-block/04-FDO-Profiles.html:135

• This sentence is grammatically malformed (One of the profile of a profile) and obscures which profile must be present in a profile definition record.

            One of the <a>profile</a> of a <a>profile</a> MUST be <a><em>0.FDO/ProfileDef</em></a>.

sections/01_fdo-building-block/05-Attributes.html:292

• The DataType table still lists an external vocabulary namespace as a valid target, but R8-1 now requires this mechanism to point to an FDO following 0.FDO/VocabularyDef. Leaving both forms here gives clients incompatible target shapes for the same attribute; update the legacy namespace entry or explicitly mark it obsolete.

                <li>a <a>profile</a> (see <a href="#profile-referencing"></a>)</li>
                <li>an external vocabulary namespace (see <a href="#external-vocabulary-referencing"></a>)</li>

sections/01_fdo-building-block/08-Extensions.html:5

• The moved Inline FDO section is given the inline-fdo target, but the existing Granularity reference still points to #inline-fdos while Referencing points to #inline-fdo. The Granularity link will therefore not resolve; use one canonical ID and update all callers.

<h3 id="inline-fdo"><dfn data-lt="Lambda FDO|Inline Serialization">Inline <a>FDOs</a></dfn></h3>

sections/01_fdo-building-block/08-Extensions.html:102

• This cross-reference omits the # fragment marker, so the example does not link to the newly added R8-1 rule.

    <a href="#ex-vocab-ref"></a> shows how schema.org terms can be used in an <a>FDO record</a> similar to an <a>attribute definition</a> by applying <a>external vocabulary referencing</a> (see <a href="rule-r8_1"></a>).

sections/01_fdo-building-block/08-Extensions.html:142

• This cross-reference also omits the # fragment marker, so the example does not link to R8-3.

        <a>External vocabulary referencing</a> can also be used to reference a term from an external vocabulary as the value of an <a>attribute</a> (see <a href="rule-r8_3"></a>).

sections/01_fdo-building-block/08-Extensions.html:36

• Requiring prefixes to be merely unique does not make matching unambiguous: one prefix can be a prefix of another, so a term may match multiple imported vocabularies. Require a prefix-free set or define deterministic longest-prefix and ambiguity handling for clients.

        The creator of an <a>FDO record</a> MUST ensure that the prefixes of the imported vocabularies are unique.

sections/01_fdo-building-block/08-Extensions.html:27

• R8-1 now requires the external-vocabulary 0.FDO/DataType target to be a VocabularyDef FDO, but the normative DataType list in 05-Attributes.html still permits an “external vocabulary namespace,” which describes the removed model. Update that generic definition so the specification has one target model.

        An <a>attribute definition</a> <em>A</em> MUST explicitly state that it uses this feature by containing the
        <a>attribute</a> <em>(<a><em>0.FDO/ValidationMechanism</em></a>, ExternalVocabularyReference)</em>.
        The <em><a>0.FDO/DataType</a></em> <a>attribute</a> of <em>A</em> MUST refer to an <a>FDO</a> that follows the <a>profile definition</a> <a><em>0.FDO/VocabularyDef</em></a>.

sections/01_fdo-building-block/08-Extensions.html:13

• After moving this mechanism out of Advanced Referencing, the existing R5-11 cross-reference still points readers to #advanced-ref, which no longer contains External Vocabulary Referencing. Update that normative pointer (or link it to this section) so implementers find the requirements.

<h3 id="external-vocabulary-referencing"><dfn>External Vocabulary Referencing</dfn></h3>

sections/01_fdo-building-block/08-Extensions.html:27

• This rule conflates two different mechanisms. Under the profile-reference rules, 0.FDO/DataType identifies the target profile (for example 0.FDO/VocabularyDef) and the attribute definition must declare ProfileReference; requiring ExternalVocabularyReference here leaves the ImportVocabulary example's target validation undefined. Define ImportVocabulary with ProfileReference/0.FDO/VocabularyDef, and reserve ExternalVocabularyReference for validating vocabulary terms.

        An <a>attribute definition</a> <em>A</em> MUST explicitly state that it uses this feature by containing the
        <a>attribute</a> <em>(<a><em>0.FDO/ValidationMechanism</em></a>, ExternalVocabularyReference)</em>.
        The <em><a>0.FDO/DataType</a></em> <a>attribute</a> of <em>A</em> MUST refer to an <a>FDO</a> that follows the <a>profile definition</a> <a><em>0.FDO/VocabularyDef</em></a>.

sections/01_fdo-building-block/08-Extensions.html:142

• This example is about an attribute definition applying external vocabulary referencing, so it should cite R8-1 (the declaration rule), not R8-3 (the Vocabulary Definition Profile). The link also lacks the # fragment prefix and is therefore broken.

        <a>External vocabulary referencing</a> can also be used to reference a term from an external vocabulary as the value of an <a>attribute</a> (see <a href="rule-r8_3"></a>).

• Files reviewed: 33/39 changed files
• Comments generated: 5
• Review effort level: Lite