Skip to content

Update metadata reference #201

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Sep 25, 2025
Merged

Update metadata reference #201

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
c1ccb62
Improve refItem style
Ndpnt Sep 25, 2025
6ce988f
Lint
Ndpnt Sep 25, 2025
dbc0ad3
Add script to generate metadata reference documentation
Ndpnt Sep 25, 2025
002e559
Update metadata reference documentation
Ndpnt Sep 25, 2025
d41907a
Add comments to prevent manual edition of generated doc
Ndpnt Sep 25, 2025
6a74981
Add readme instructions
clementbiron Sep 25, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -99,6 +99,14 @@ To check for broken links, run the following command:
npm run test:links
```

### Generate collection metadata reference

To generate collection metadata reference, run the following command:

```sh
npm run generate-metadata-reference
```

## Deployment

The `main` branch is used on production and automatically deployed through GitHub pages. Refer to the configuration file `.github/workflows/gh-pages.yml`.
Expand Down
50 changes: 36 additions & 14 deletions content/collections/reference/metadata.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,10 @@ This reference documentation details all available metadata fields that can be s

The examples given throughout this reference can be seen in context in the [complete metadata file](https://github.com/OpenTermsArchive/demo-declarations/blob/main/metadata.yml) and rendered in the [collection page](https://opentermsarchive.org/en/collections/demo/) of the Demo collection.


<!-- GENERATED DOCUMENTATION DO NOT EDIT THE FOLLOWING SECTION MANUALLY -->
## Fields

<!-- GENERATED DOCUMENTATION DO NOT EDIT THIS MANUALLY -->
{{< refItem
name="id"
type="string"
Expand All @@ -21,6 +22,7 @@ The examples given throughout this reference can be seen in context in the [comp
required=true
/>}}

<!-- GENERATED DOCUMENTATION DO NOT EDIT THIS MANUALLY -->
{{< refItem
name="name"
type="string"
Expand All @@ -29,14 +31,16 @@ The examples given throughout this reference can be seen in context in the [comp
required=true
/>}}

<!-- GENERATED DOCUMENTATION DO NOT EDIT THIS MANUALLY -->
{{< refItem
name="tagline"
type="string"
description="Concise description of collection topic."
example="Services used by Open Terms Archive"
example="Services used by Open Terms Archive"
required=true
/>}}

<!-- GENERATED DOCUMENTATION DO NOT EDIT THIS MANUALLY -->
{{< refItem
name="languages"
type="array of strings"
Expand All @@ -45,6 +49,7 @@ The examples given throughout this reference can be seen in context in the [comp
required=true
/>}}

<!-- GENERATED DOCUMENTATION DO NOT EDIT THIS MANUALLY -->
{{< refItem
name="jurisdictions"
type="array of strings"
Expand All @@ -53,21 +58,22 @@ The examples given throughout this reference can be seen in context in the [comp
required=true
/>}}

<!-- GENERATED DOCUMENTATION DO NOT EDIT THIS MANUALLY -->
{{< refItem
name="description"
type="string"
description="Detailed description of the collection"
required=false
>}}

```yaml
description: >
The **Demo** collection tracks changes to the terms of use of services used by Open Terms Archive.
The **Demo** collection tracks changes to the terms of use of services used by Open Terms Archive.

This provides a reference collection for best practices and enables the Open Terms Archive Core Team to be a user of the software it produces.

This provides a reference collection for best practices and enables the Open Terms Archive Core Team to be a user of the software it produces.
```
{{< /refItem >}}

<!-- GENERATED DOCUMENTATION DO NOT EDIT THIS MANUALLY -->
{{< refItem
name="dataset"
type="uri"
Expand All @@ -76,6 +82,7 @@ description: >
required=false
/>}}

<!-- GENERATED DOCUMENTATION DO NOT EDIT THIS MANUALLY -->
{{< refItem
name="declarations"
type="uri"
Expand All @@ -84,6 +91,7 @@ description: >
required=false
/>}}

<!-- GENERATED DOCUMENTATION DO NOT EDIT THIS MANUALLY -->
{{< refItem
name="versions"
type="uri"
Expand All @@ -92,6 +100,7 @@ description: >
required=false
/>}}

<!-- GENERATED DOCUMENTATION DO NOT EDIT THIS MANUALLY -->
{{< refItem
name="snapshots"
type="uri"
Expand All @@ -100,6 +109,7 @@ description: >
required=false
/>}}

<!-- GENERATED DOCUMENTATION DO NOT EDIT THIS MANUALLY -->
{{< refItem
name="donations"
type="uri"
Expand All @@ -108,6 +118,7 @@ description: >
required=false
/>}}

<!-- GENERATED DOCUMENTATION DO NOT EDIT THIS MANUALLY -->
{{< refItem
name="logo"
type="uri"
Expand All @@ -116,20 +127,23 @@ description: >
required=false
/>}}

<!-- GENERATED DOCUMENTATION DO NOT EDIT THIS MANUALLY -->
{{< refItem
name="trackingPeriods"
type="array of objects"
description="List of time periods during which terms were tracked, with their tracking configuration. Gaps between periods indicate times when tracking was interrupted. See [TrackingPeriods]({{< relref \"#trackingperiods\" >}}) section."
required=false
/>}}

<!-- GENERATED DOCUMENTATION DO NOT EDIT THIS MANUALLY -->
{{< refItem
name="governance"
type="object of objects"
description="Map of organizations involved in the collection's governance, with organization names as keys and governance objects as values. See [Governance]({{< relref \"#governance\" >}}) section."
required=false
/>}}

<!-- GENERATED DOCUMENTATION DO NOT EDIT THIS MANUALLY -->
{{< refItem
name="i18n"
type="object of objects"
Expand All @@ -138,19 +152,21 @@ description: >
>}}
```yaml
fr:
name: Démo
tagline: Services utilisés par Open Terms Archive
governance:
name: Démo
tagline: Services utilisés par Open Terms Archive
governance:
Ministry for Europe and Foreign Affairs:
name: Ministère de l'Europe et des Affaires étrangères
url: https://www.diplomatie.gouv.fr
name: Ministère de l'Europe et des Affaires étrangères
url: https://www.diplomatie.gouv.fr

```
{{< /refItem >}}

---

### TrackingPeriods

<!-- GENERATED DOCUMENTATION DO NOT EDIT THIS MANUALLY -->
{{< refItem
name="startDate"
type="date"
Expand All @@ -159,6 +175,7 @@ fr:
required=true
/>}}

<!-- GENERATED DOCUMENTATION DO NOT EDIT THIS MANUALLY -->
{{< refItem
name="schedule"
type="cron-expression"
Expand All @@ -167,6 +184,7 @@ fr:
required=true
/>}}

<!-- GENERATED DOCUMENTATION DO NOT EDIT THIS MANUALLY -->
{{< refItem
name="serverLocation"
type="string"
Expand All @@ -175,6 +193,7 @@ fr:
required=true
/>}}

<!-- GENERATED DOCUMENTATION DO NOT EDIT THIS MANUALLY -->
{{< refItem
name="endDate"
type="date"
Expand All @@ -188,6 +207,7 @@ fr:

### Governance

<!-- GENERATED DOCUMENTATION DO NOT EDIT THIS MANUALLY -->
{{< refItem
name="url"
type="uri"
Expand All @@ -196,6 +216,7 @@ fr:
required=false
/>}}

<!-- GENERATED DOCUMENTATION DO NOT EDIT THIS MANUALLY -->
{{< refItem
name="logo"
type="uri"
Expand All @@ -204,11 +225,12 @@ fr:
required=false
/>}}

<!-- GENERATED DOCUMENTATION DO NOT EDIT THIS MANUALLY -->
{{< refItem
name="roles"
type="array of strings"
description="Roles of the entity within the governance, see [collection governance](https://docs.opentermsarchive.org/collections/reference/roles/)"
allowedValues="host, administrator, curator, maintainer, sponsor"
example="[host, administrator]"
description="Roles of the entity within the governance, see [collection governance](https://docs.opentermsarchive.org/collections/reference/governance/)"
allowedValues="`host`, `sysadmin`, `curator`, `maintainer`, `contributor`, `analyst`, `diffuser`, `sponsor`"
example="[host, sysadmin]"
required=true
/>}}
Loading