From 033b45b99a188da7f0b9df3302897af747fb9cbc Mon Sep 17 00:00:00 2001 From: Nicolas Dupont Date: Wed, 19 Feb 2025 17:20:12 +0100 Subject: [PATCH 1/8] Update metadata reference --- content/collections/reference/metadata.md | 149 ++++++++++-------- .../layouts/shortcodes/configOption.html | 2 +- 2 files changed, 82 insertions(+), 69 deletions(-) diff --git a/content/collections/reference/metadata.md b/content/collections/reference/metadata.md index 2ee2083d..b88d97fe 100644 --- a/content/collections/reference/metadata.md +++ b/content/collections/reference/metadata.md @@ -17,15 +17,15 @@ As an example, see the [complete metadata file](https://github.com/OpenTermsArch name="id" type="string" description="Unique identifier derived from name (acronyms, dash-separated)." - example="`pga`" + example="pga" required=true >}} {{< configOption name="name" type="string" - description="Display name of the collection (max 3 words)." - example="`Platform Governance Archive`" + description="Display name of the collection." + example="Platform Governance Archive" required=true >}} @@ -33,117 +33,126 @@ As an example, see the [complete metadata file](https://github.com/OpenTermsArch name="tagline" type="string" description="Concise description of collection topic." - example="`Major global social media services`" + example="Major global social media services" required=true >}} {{< configOption name="languages" - type="Array of strings" - description="[ISO 639 language codes](https://en.wikipedia.org/wiki/ISO_639) allowed in collection." - example="`[en, fr, de]`" + type="array of strings" + description="List of [ISO 639-1 (two-letter)](https://en.wikipedia.org/wiki/ISO_639) language codes representing languages allowed in the collection." + example="[en, fr, de]" required=true >}} {{< configOption name="jurisdictions" - type="Array of strings" - description="[ISO 3166-2 country codes](https://en.wikipedia.org/wiki/ISO_3166-2) for covered jurisdictions." - example="`[EU]`" + type="array of strings" + description="List of [ISO 3166-2 country codes](https://en.wikipedia.org/wiki/ISO_3166-2) representing jurisdictions covered by the collection." + example="[EU]" required=true >}} {{< configOption name="description" type="string" - description="Detailed description of the collection." + description="Detailed description of the collection" example=`The **Platform Governance Archive** (PGA) collection tracks the terms of major global social media services. This data is maintained and analysed by the [Platform Governance Archive](https://www.platformgovernancearchive.org/) at the Universität Bremen's [Center for Media Communication and Information Research (ZeMKI)](https://www.uni-bremen.de/zemki). This initiative offers researchers, journalists and citizens the tools to analyze how platforms structure and regulate communication and interaction in our societies. -It also aims to promote greater transparency and accountability of these powerful digital services.` +It also aims to promote greater transparency and accountability of these powerful digital services. +` + required=false >}} - + {{< configOption name="dataset" - type="url" - description="URL to released versions dataset." - example="`https://github.com/OpenTermsArchive/pga-versions/releases`" + type="uri" + description="URL to the dataset releases." + example="https://github.com/OpenTermsArchive/pga-versions/releases" + required=false >}} {{< configOption name="declarations" - type="url" - description="URL to declarations repository." - example="`https://github.com/OpenTermsArchive/pga-declarations`" + type="uri" + description="URL to the declarations repository." + example="https://github.com/OpenTermsArchive/pga-declarations" + required=false >}} {{< configOption name="versions" - type="url" - description="URL to versions repository." - example="`https://github.com/OpenTermsArchive/pga-versions`" + type="uri" + description="URL to the versions repository." + example="https://github.com/OpenTermsArchive/pga-versions" + required=false >}} {{< configOption name="snapshots" - type="url" - description="URL to snapshots repository." - example="`https://github.com/OpenTermsArchive/pga-snapshots`" + type="uri" + description="URL to the snapshots repository." + example="https://github.com/OpenTermsArchive/pga-snapshots" + required=false >}} {{< configOption - name="logo" - type="url" - description="URL to the collection's logo. Optimized PNG transparent image (min width 240px)." - example="`https://opentermsarchive.org/images/collections/pga.png`" + name="donations" + type="uri" + description="URL to the donations page." + example="https://opencollective.com/opentermsarchive" + required=false >}} {{< configOption - name="donations" - type="url" - description="URL to the donations page." - example="`https://opencollective.com/opentermsarchive`" + name="logo" + type="uri" + description="URL to the collection's logo. Optimized PNG transparent image (min width 240px)." + required=false >}} {{< configOption name="trackingPeriods" - type="array of tracking periods objects" - description="Tracking periods object, see [Tracking periods](#tracking-periods) section." + type="array of objects" + description="trackingPeriods object, see [TrackingPeriods](#trackingperiods) section." + required=false >}} {{< configOption name="governance" - type="array of entity objects" - description="Entity object, see [Entity](#entity) section." + type="object" + description="Map of organizations involved in the collection's governance, with organization names as keys governance object, see [Governance](#governance) section." + required=false +>}} + +{{< configOption + name="i18n" + type="object" + description="Internationalization of any of the Metadata properties (except i18n itself) for different language codes" + required=false >}} --- -### Tracking periods +### TrackingPeriods {{< configOption name="startDate" type="date" - description="The date when tracking started (ISO 8601 format: YYYY-MM-DD)." - example="`2023-01-01`" + description="The date when tracking started for this period (ISO 8601 format YYYY-MM-DD)." + example="2023-01-01" required=true >}} -{{< configOption - name="endDate" - type="date" - description="The date when tracking ended or will end. If not specified, tracking is ongoing." - example="`2024-12-31`" ->}} - {{< configOption name="schedule" - type="string" + type="cron-expression" description="A [cron expression](https://en.wikipedia.org/wiki/Cron#Cron_expression) that defines the tracking frequency." - example="`0 0 * * *`" + example="0 0 * * *" required=true >}} @@ -151,40 +160,44 @@ It also aims to promote greater transparency and accountability of these powerfu name="serverLocation" type="string" description="The geographic location of the tracking server (city name, ISO 3166-2 country code)." - example="`London, GB`" + example="London, GB" required=true >}} ---- - -### Entity - {{< configOption - name="name" - type="string" - description="Name of the organization." - example="`Open Terms Archive`" - required=true + name="endDate" + type="date" + description="The date when tracking ended for this period (ISO 8601 format YYYY-MM-DD). If not specified, tracking is ongoing." + example="2023-12-01" + required=false >}} + +--- + +### Governance + {{< configOption name="url" - type="url" - description="Website URL of the organization." - example="`https://opentermsarchive.org/`" + type="uri" + description="URL to the entity's website" + example="https://opentermsarchive.org/" + required=false >}} {{< configOption name="logo" - type="url" - description="URL to the organization's logo. Optimized PNG transparent image (min width 240px)." - example="`https://opentermsarchive.org/images/logo/logo-open-terms-archive-black.png`" + type="uri" + description="URL to the entity's logo. Optimized PNG transparent image (min width 240px)." + example="https://opentermsarchive.org/images/logo/logo-open-terms-archive-black.png" + required=false >}} {{< configOption name="roles" - type="string" - description="Roles of the entity within the governance, see [collection governance]({{< relref \"collections/reference/governance\" >}})." + type="array of strings" + description="Roles of the entity within the governance, see [collection governance](https://docs.opentermsarchive.org/collections/reference/governance/)" allowedValues="`host`, `administrator`, `curator`, `maintainer`, `sponsor`" - required=true + example="[host, administrator]" + required=false >}} diff --git a/themes/opentermsarchive/layouts/shortcodes/configOption.html b/themes/opentermsarchive/layouts/shortcodes/configOption.html index c9645205..0bf87c84 100644 --- a/themes/opentermsarchive/layouts/shortcodes/configOption.html +++ b/themes/opentermsarchive/layouts/shortcodes/configOption.html @@ -12,7 +12,7 @@
Default:{{ .Get "default" | markdownify}}
{{ end }} {{ if .Get "example" }} -
Example:{{ .Get "example" | markdownify }}
+
Example:{{ .Get "example" | markdownify }}
{{ end }} {{ if .Get "allowedValues" }}
Allowed values:{{ .Get "allowedValues" | markdownify }}
From 0d84b564b70fd22fa555b7ad3ed34ca1a2a30439 Mon Sep 17 00:00:00 2001 From: Nicolas Dupont Date: Mon, 3 Mar 2025 16:02:32 +0100 Subject: [PATCH 2/8] Improve display of multiline examples --- .../layouts/shortcodes/configOption.html | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/themes/opentermsarchive/layouts/shortcodes/configOption.html b/themes/opentermsarchive/layouts/shortcodes/configOption.html index 0bf87c84..99b48f03 100644 --- a/themes/opentermsarchive/layouts/shortcodes/configOption.html +++ b/themes/opentermsarchive/layouts/shortcodes/configOption.html @@ -12,7 +12,14 @@
Default:{{ .Get "default" | markdownify}}
{{ end }} {{ if .Get "example" }} -
Example:{{ .Get "example" | markdownify }}
+
Example: + {{ $example := .Get "example" }} + {{ if not (strings.Contains $example "\n") }} + {{ $example | markdownify }} + {{ else }} + {{ $example | markdownify }} + {{ end }} +
{{ end }} {{ if .Get "allowedValues" }}
Allowed values:{{ .Get "allowedValues" | markdownify }}
From a3b44014601c44c4445a30d1b82f2a20aa5529a7 Mon Sep 17 00:00:00 2001 From: Nicolas Dupont Date: Mon, 3 Mar 2025 16:02:45 +0100 Subject: [PATCH 3/8] Update metadata specs --- content/collections/reference/metadata.md | 45 +++++++++++++---------- 1 file changed, 25 insertions(+), 20 deletions(-) diff --git a/content/collections/reference/metadata.md b/content/collections/reference/metadata.md index b88d97fe..f01c9ba2 100644 --- a/content/collections/reference/metadata.md +++ b/content/collections/reference/metadata.md @@ -17,7 +17,7 @@ As an example, see the [complete metadata file](https://github.com/OpenTermsArch name="id" type="string" description="Unique identifier derived from name (acronyms, dash-separated)." - example="pga" + example="demo" required=true >}} @@ -25,7 +25,7 @@ As an example, see the [complete metadata file](https://github.com/OpenTermsArch name="name" type="string" description="Display name of the collection." - example="Platform Governance Archive" + example="Demo Collection" required=true >}} @@ -33,7 +33,7 @@ As an example, see the [complete metadata file](https://github.com/OpenTermsArch name="tagline" type="string" description="Concise description of collection topic." - example="Major global social media services" + example="Services used by Open Terms Archive" required=true >}} @@ -57,14 +57,10 @@ As an example, see the [complete metadata file](https://github.com/OpenTermsArch name="description" type="string" description="Detailed description of the collection" - example=`The **Platform Governance Archive** (PGA) collection tracks the terms of major global social media services. - -This data is maintained and analysed by the [Platform Governance Archive](https://www.platformgovernancearchive.org/) at the Universität Bremen's [Center for Media Communication and Information Research (ZeMKI)](https://www.uni-bremen.de/zemki). - -This initiative offers researchers, journalists and citizens the tools to analyze how platforms structure and regulate communication and interaction in our societies. - -It also aims to promote greater transparency and accountability of these powerful digital services. -` + example=` 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. + ` required=false >}} @@ -72,7 +68,7 @@ It also aims to promote greater transparency and accountability of these powerfu name="dataset" type="uri" description="URL to the dataset releases." - example="https://github.com/OpenTermsArchive/pga-versions/releases" + example="https://github.com/OpenTermsArchive/demo-versions/releases" required=false >}} @@ -80,7 +76,7 @@ It also aims to promote greater transparency and accountability of these powerfu name="declarations" type="uri" description="URL to the declarations repository." - example="https://github.com/OpenTermsArchive/pga-declarations" + example="https://github.com/OpenTermsArchive/demo-declarations" required=false >}} @@ -88,7 +84,7 @@ It also aims to promote greater transparency and accountability of these powerfu name="versions" type="uri" description="URL to the versions repository." - example="https://github.com/OpenTermsArchive/pga-versions" + example="https://github.com/OpenTermsArchive/demo-versions" required=false >}} @@ -96,7 +92,7 @@ It also aims to promote greater transparency and accountability of these powerfu name="snapshots" type="uri" description="URL to the snapshots repository." - example="https://github.com/OpenTermsArchive/pga-snapshots" + example="https://github.com/OpenTermsArchive/demo-snapshots" required=false >}} @@ -111,7 +107,8 @@ It also aims to promote greater transparency and accountability of these powerfu {{< configOption name="logo" type="uri" - description="URL to the collection's logo. Optimized PNG transparent image (min width 240px)." + description="URL to the collection's logo. Optimized PNG transparent image (minimum width 240px)." + example="https://opentermsarchive.org/images/logo/logo-open-terms-archive-black.png" required=false >}} @@ -133,6 +130,14 @@ It also aims to promote greater transparency and accountability of these powerfu name="i18n" type="object" description="Internationalization of any of the Metadata properties (except i18n itself) for different language codes" + example=` fr: + 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 + ` required=false >}} @@ -159,8 +164,8 @@ It also aims to promote greater transparency and accountability of these powerfu {{< configOption name="serverLocation" type="string" - description="The geographic location of the tracking server (city name, ISO 3166-2 country code)." - example="London, GB" + description="The geographic location of the tracking server (city name and ISO 3166-2 country code)." + example="Paris, FR" required=true >}} @@ -188,7 +193,7 @@ It also aims to promote greater transparency and accountability of these powerfu {{< configOption name="logo" type="uri" - description="URL to the entity's logo. Optimized PNG transparent image (min width 240px)." + description="URL to the entity's logo. Optimized PNG transparent image (minimum width 240px)." example="https://opentermsarchive.org/images/logo/logo-open-terms-archive-black.png" required=false >}} @@ -199,5 +204,5 @@ It also aims to promote greater transparency and accountability of these powerfu description="Roles of the entity within the governance, see [collection governance](https://docs.opentermsarchive.org/collections/reference/governance/)" allowedValues="`host`, `administrator`, `curator`, `maintainer`, `sponsor`" example="[host, administrator]" - required=false + required=true >}} From 64c53fd8aa056317639f136e77e6cae8e100f81b Mon Sep 17 00:00:00 2001 From: Matti Schneider Date: Tue, 4 Mar 2025 10:16:49 +0700 Subject: [PATCH 4/8] Add link to rendered metadata page --- content/collections/reference/metadata.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/collections/reference/metadata.md b/content/collections/reference/metadata.md index f01c9ba2..a4baa536 100644 --- a/content/collections/reference/metadata.md +++ b/content/collections/reference/metadata.md @@ -8,7 +8,7 @@ aliases: /collections/metadata/ This reference documentation details all available metadata fields that can be specified in a collection's metadata file. -As an example, see the [complete metadata file](https://github.com/OpenTermsArchive/demo-declarations/blob/main/metadata.yml) of the [Demo collection](https://github.com/OpenTermsArchive/demo-declarations). +As an example, see the [complete metadata file](https://github.com/OpenTermsArchive/demo-declarations/blob/main/metadata.yml) and the resulting [rendered description](https://opentermsarchive.org/en/collections/demo/) of the Demo collection. ## Fields From 0d0d209e424414b1acf0356c7dc5d5bfb30b1276 Mon Sep 17 00:00:00 2001 From: Matti Schneider Date: Tue, 4 Mar 2025 10:18:10 +0700 Subject: [PATCH 5/8] =?UTF-8?q?Avoid=20using=20=E2=80=9Cyou=E2=80=9D=20in?= =?UTF-8?q?=20copywriting?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- content/collections/reference/metadata.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/collections/reference/metadata.md b/content/collections/reference/metadata.md index a4baa536..3df52b0b 100644 --- a/content/collections/reference/metadata.md +++ b/content/collections/reference/metadata.md @@ -8,7 +8,7 @@ aliases: /collections/metadata/ This reference documentation details all available metadata fields that can be specified in a collection's metadata file. -As an example, see the [complete metadata file](https://github.com/OpenTermsArchive/demo-declarations/blob/main/metadata.yml) and the resulting [rendered description](https://opentermsarchive.org/en/collections/demo/) of the Demo collection. +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. ## Fields From 54cc1b8bd06b12bfe4ad5177ed765eaa6cd049e2 Mon Sep 17 00:00:00 2001 From: Matti Schneider Date: Tue, 4 Mar 2025 10:19:54 +0700 Subject: [PATCH 6/8] Correct double blank space --- content/collections/reference/metadata.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/collections/reference/metadata.md b/content/collections/reference/metadata.md index 3df52b0b..94e5a0f1 100644 --- a/content/collections/reference/metadata.md +++ b/content/collections/reference/metadata.md @@ -8,7 +8,7 @@ aliases: /collections/metadata/ This reference documentation details all available metadata fields that can be specified in a collection's metadata file. -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. +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. ## Fields From 1472a5d43f35d8010c64d57d65d2a35b08405aa5 Mon Sep 17 00:00:00 2001 From: Matti Schneider Date: Tue, 4 Mar 2025 10:20:42 +0700 Subject: [PATCH 7/8] Correct description --- content/collections/reference/metadata.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/collections/reference/metadata.md b/content/collections/reference/metadata.md index 94e5a0f1..0ccb3d24 100644 --- a/content/collections/reference/metadata.md +++ b/content/collections/reference/metadata.md @@ -122,7 +122,7 @@ The examples given throughout this reference can be seen in context in the [comp {{< configOption name="governance" type="object" - description="Map of organizations involved in the collection's governance, with organization names as keys governance object, see [Governance](#governance) section." + description="Map of organizations involved in the collection's governance, with organization names as keys and [governance objects](#governance) as values." required=false >}} From dbe1f40cf44e56662d0a2352cb6ae2b58a3d5a71 Mon Sep 17 00:00:00 2001 From: Nicolas Dupont Date: Tue, 4 Mar 2025 09:26:19 +0100 Subject: [PATCH 8/8] Update Metadata specs --- content/collections/reference/metadata.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/content/collections/reference/metadata.md b/content/collections/reference/metadata.md index 0ccb3d24..6daa747d 100644 --- a/content/collections/reference/metadata.md +++ b/content/collections/reference/metadata.md @@ -115,20 +115,20 @@ The examples given throughout this reference can be seen in context in the [comp {{< configOption name="trackingPeriods" type="array of objects" - description="trackingPeriods object, see [TrackingPeriods](#trackingperiods) section." + 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 >}} {{< configOption name="governance" - type="object" - description="Map of organizations involved in the collection's governance, with organization names as keys and [governance objects](#governance) as values." + 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 >}} {{< configOption name="i18n" - type="object" + type="object of objects" description="Internationalization of any of the Metadata properties (except i18n itself) for different language codes" example=` fr: name: Démo