odata-vocabularies-sync

Keeps the packages/odata-vocabularies package in sync with the upstream OData vocabulary sources.

• No argument — update all existing vocabulary resource files to their latest published versions.
• With a URL argument — register and add the new vocabulary first, then update everything.

All file edits are relative to packages/odata-vocabularies/.

Note: com.sap.cds.vocabularies.* files (ObjectModel, AnalyticsDetails) are hand-crafted and not managed by this skill. Do not attempt to add them via a URL.

Step 1 — Add a new vocabulary (only when a URL argument is provided)

1a. Fetch and inspect the vocabulary JSON

Fetch the JSON at the provided URL (must end in .json — XML URLs are not supported by the update tool). Extract:

• namespace — the key of the top-level schema object (e.g. Org.OData.NewThing.V1 or com.sap.vocabularies.NewThing.v1)
• alias — the value of $Alias inside that schema object (e.g. NewThing)

Determine the vocabulary family from the namespace:

• Starts with Org.OData. → OASIS vocabulary
• Starts with com.sap.vocabularies. → SAP vocabulary
• Starts with com.sap.cds. → CDS vocabulary — stop. These files are hand-crafted and cannot be added via this skill. Explain this to the user.
• Anything else → stop and ask the user to confirm the family before proceeding.

1b. Edit tools/update.ts

Add an entry to SUPPORTED_VOCABULARIES in alphabetical order within the existing entries:

'<namespace>': {
    uri: '<the provided URL>'
},

Note: The entry can include update: false to pin the vocabulary and exclude it from future automatic updates (e.g. com.sap.vocabularies.CDS.v1 uses this because it is hand-maintained). Omit the field for normal auto-updating behaviour.

1c. Edit src/resources/index.ts

Make all six additions. All six are mandatory — missing any one will cause a runtime error.

1. Import — insert alphabetically by alias in the single import block (OASIS and SAP imports are interleaved by alias, not grouped by family):

   import <Alias> from './<namespace>.js';
   

   Use the $Alias value from the JSON as the import identifier. Exception: if the alias is a reserved JS keyword or built-in (e.g. JSON, Map, Error), prefix it to form a valid identifier (e.g. JSON → ODataJSON). Also check existing imports for precedent — some aliases are shortened for brevity (e.g. Authorization → Auth).

2. Namespace union type — add to the matching family type:

   • OASIS → OasisVocabularyNamespace
   • SAP → SapVocabularyNamespace

   | '<namespace>'
   

3. Alias union type — add to the matching family type:

   • OASIS → OasisVocabularyAlias
   • SAP → SapVocabularyAlias

   | '<Alias>'
   

4. NAMESPACE_TO_ALIAS Map:

   ['<namespace>', '<Alias>'],
   

5. ALIAS_TO_NAMESPACE Map:

   ['<Alias>', '<namespace>'],
   

6. vocabularies Record:

   '<namespace>': <Alias>,
   

1d. Edit src/loader.ts

Add the namespace to SUPPORTED_VOCABULARY_NAMESPACES in alphabetical order within its family block:

'<namespace>',

1e. Edit README.md

Add the alias to the correct bullet list in the "Supported Vocabularies" section, in alphabetical order:

• OASIS namespace → OASIS Vocabularies list
• SAP namespace → SAP Vocabularies list

* <Alias>

Step 2 — Run the update tool

This fetches the latest JSON for every registered vocabulary (including any newly added one) and regenerates all src/resources/*.ts resource files.

Run from the repo root:

pnpm --filter @sap-ux/odata-vocabularies update:vocabularies

If the tool fails, stop and report the full error output before proceeding.

Step 3 — Audit and fix README

Cross-check the README against the registered vocabularies and add any missing entries.

1. Read src/resources/index.ts and collect all namespaces from NAMESPACE_TO_ALIAS, split by family:

   • OASIS: namespaces starting with Org.OData.
   • SAP: namespaces starting with com.sap.vocabularies. excluding com.sap.vocabularies.CDS.v1
   • Skip all com.sap.cds. namespaces (hand-crafted, not listed in README)

2. For each collected namespace, read the corresponding generated resource file src/resources/<namespace>.ts and extract the $Alias value — this is the authoritative published alias used as the display name in README.

3. Read README.md and find the two bullet lists under "Supported Vocabularies":

   • The OASIS Vocabularies list
   • The SAP Vocabularies list

4. For each alias not yet present in the correct list, insert it in alphabetical order.

If the README is already complete, do nothing.

Step 4 — Run tests and update snapshots

pnpm --filter @sap-ux/odata-vocabularies test -- -u

Report any test failures that are not snapshot-related. Snapshot updates are expected only when vocabulary content has actually changed (either upstream drift detected by the update tool, or a newly added vocabulary). If snapshots change beyond what was updated, inspect the diff before accepting — it may indicate a regression.

Step 5 — Report

Summarise what was done:

• If a new vocabulary was added: confirm the namespace, alias, family, and all files changed.
• If any README entries were missing and added, list them.
• List vocabulary resource files regenerated by the update tool.
• Confirm tests pass.