Skip to content

Commit d45eb41

Browse files
NdpntNdpnt
authored
Update metadata reference (#162)
2 parents 8393fe7 + dbe1f40 commit d45eb41

File tree

2 files changed

+101
-76
lines changed

2 files changed

+101
-76
lines changed

‎content/collections/reference/metadata.md

+93-75
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ aliases: /collections/metadata/
88

99
This reference documentation details all available metadata fields that can be specified in a collection's metadata file.
1010

11-
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).
11+
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.
1212

1313

1414
## Fields
@@ -17,174 +17,192 @@ As an example, see the [complete metadata file](https://github.com/OpenTermsArch
1717
name="id"
1818
type="string"
1919
description="Unique identifier derived from name (acronyms, dash-separated)."
20-
example="`pga`"
20+
example="demo"
2121
required=true
2222
>}}
2323
2424
{{< configOption
2525
name="name"
2626
type="string"
27-
description="Display name of the collection (max 3 words)."
28-
example="`Platform Governance Archive`"
27+
description="Display name of the collection."
28+
example="Demo Collection"
2929
required=true
3030
>}}
3131
3232
{{< configOption
3333
name="tagline"
3434
type="string"
3535
description="Concise description of collection topic."
36-
example="`Major global social media services`"
36+
example="Services used by Open Terms Archive"
3737
required=true
3838
>}}
3939
4040
{{< configOption
4141
name="languages"
42-
type="Array of strings"
43-
description="[ISO 639 language codes](https://en.wikipedia.org/wiki/ISO_639) allowed in collection."
44-
example="`[en, fr, de]`"
42+
type="array of strings"
43+
description="List of [ISO 639-1 (two-letter)](https://en.wikipedia.org/wiki/ISO_639) language codes representing languages allowed in the collection."
44+
example="[en, fr, de]"
4545
required=true
4646
>}}
4747
4848
{{< configOption
4949
name="jurisdictions"
50-
type="Array of strings"
51-
description="[ISO 3166-2 country codes](https://en.wikipedia.org/wiki/ISO_3166-2) for covered jurisdictions."
52-
example="`[EU]`"
50+
type="array of strings"
51+
description="List of [ISO 3166-2 country codes](https://en.wikipedia.org/wiki/ISO_3166-2) representing jurisdictions covered by the collection."
52+
example="[EU]"
5353
required=true
5454
>}}
5555
5656
{{< configOption
5757
name="description"
5858
type="string"
59-
description="Detailed description of the collection."
60-
example=`The **Platform Governance Archive** (PGA) collection tracks the terms of major global social media services.
61-
62-
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).
63-
64-
This initiative offers researchers, journalists and citizens the tools to analyze how platforms structure and regulate communication and interaction in our societies.
65-
66-
It also aims to promote greater transparency and accountability of these powerful digital services.`
59+
description="Detailed description of the collection"
60+
example=` The **Demo** collection tracks changes to the terms of use of services used by Open Terms Archive.
61+
62+
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.
63+
`
64+
required=false
6765
>}}
68-
66+
6967
{{< configOption
7068
name="dataset"
71-
type="url"
72-
description="URL to released versions dataset."
73-
example="`https://github.com/OpenTermsArchive/pga-versions/releases`"
69+
type="uri"
70+
description="URL to the dataset releases."
71+
example="https://github.com/OpenTermsArchive/demo-versions/releases"
72+
required=false
7473
>}}
7574
7675
{{< configOption
7776
name="declarations"
78-
type="url"
79-
description="URL to declarations repository."
80-
example="`https://github.com/OpenTermsArchive/pga-declarations`"
77+
type="uri"
78+
description="URL to the declarations repository."
79+
example="https://github.com/OpenTermsArchive/demo-declarations"
80+
required=false
8181
>}}
8282
8383
{{< configOption
8484
name="versions"
85-
type="url"
86-
description="URL to versions repository."
87-
example="`https://github.com/OpenTermsArchive/pga-versions`"
85+
type="uri"
86+
description="URL to the versions repository."
87+
example="https://github.com/OpenTermsArchive/demo-versions"
88+
required=false
8889
>}}
8990
9091
{{< configOption
9192
name="snapshots"
92-
type="url"
93-
description="URL to snapshots repository."
94-
example="`https://github.com/OpenTermsArchive/pga-snapshots`"
93+
type="uri"
94+
description="URL to the snapshots repository."
95+
example="https://github.com/OpenTermsArchive/demo-snapshots"
96+
required=false
9597
>}}
9698
9799
{{< configOption
98-
name="logo"
99-
type="url"
100-
description="URL to the collection's logo. Optimized PNG transparent image (min width 240px)."
101-
example="`https://opentermsarchive.org/images/collections/pga.png`"
100+
name="donations"
101+
type="uri"
102+
description="URL to the donations page."
103+
example="https://opencollective.com/opentermsarchive"
104+
required=false
102105
>}}
103106
104107
{{< configOption
105-
name="donations"
106-
type="url"
107-
description="URL to the donations page."
108-
example="`https://opencollective.com/opentermsarchive`"
108+
name="logo"
109+
type="uri"
110+
description="URL to the collection's logo. Optimized PNG transparent image (minimum width 240px)."
111+
example="https://opentermsarchive.org/images/logo/logo-open-terms-archive-black.png"
112+
required=false
109113
>}}
110114
111115
{{< configOption
112116
name="trackingPeriods"
113-
type="array of tracking periods objects"
114-
description="Tracking periods object, see [Tracking periods](#tracking-periods) section."
117+
type="array of objects"
118+
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."
119+
required=false
115120
>}}
116121
117122
{{< configOption
118123
name="governance"
119-
type="array of entity objects"
120-
description="Entity object, see [Entity](#entity) section."
124+
type="object of objects"
125+
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."
126+
required=false
127+
>}}
128+
129+
{{< configOption
130+
name="i18n"
131+
type="object of objects"
132+
description="Internationalization of any of the Metadata properties (except i18n itself) for different language codes"
133+
example=` fr:
134+
name: Démo
135+
tagline: Services utilisés par Open Terms Archive
136+
governance:
137+
Ministry for Europe and Foreign Affairs:
138+
name: Ministère de l'Europe et des Affaires étrangères
139+
url: https://www.diplomatie.gouv.fr
140+
`
141+
required=false
121142
>}}
122143
123144
---
124145

125-
### Tracking periods
146+
### TrackingPeriods
126147

127148
{{< configOption
128149
name="startDate"
129150
type="date"
130-
description="The date when tracking started (ISO 8601 format: YYYY-MM-DD)."
131-
example="`2023-01-01`"
151+
description="The date when tracking started for this period (ISO 8601 format YYYY-MM-DD)."
152+
example="2023-01-01"
132153
required=true
133154
>}}
134155
135-
{{< configOption
136-
name="endDate"
137-
type="date"
138-
description="The date when tracking ended or will end. If not specified, tracking is ongoing."
139-
example="`2024-12-31`"
140-
>}}
141-
142156
{{< configOption
143157
name="schedule"
144-
type="string"
158+
type="cron-expression"
145159
description="A [cron expression](https://en.wikipedia.org/wiki/Cron#Cron_expression) that defines the tracking frequency."
146-
example="`0 0 * * *`"
160+
example="0 0 * * *"
147161
required=true
148162
>}}
149163
150164
{{< configOption
151165
name="serverLocation"
152166
type="string"
153-
description="The geographic location of the tracking server (city name, ISO 3166-2 country code)."
154-
example="`London, GB`"
167+
description="The geographic location of the tracking server (city name and ISO 3166-2 country code)."
168+
example="Paris, FR"
155169
required=true
156170
>}}
157171
158-
---
159-
160-
### Entity
161-
162172
{{< configOption
163-
name="name"
164-
type="string"
165-
description="Name of the organization."
166-
example="`Open Terms Archive`"
167-
required=true
173+
name="endDate"
174+
type="date"
175+
description="The date when tracking ended for this period (ISO 8601 format YYYY-MM-DD). If not specified, tracking is ongoing."
176+
example="2023-12-01"
177+
required=false
168178
>}}
169179
180+
181+
---
182+
183+
### Governance
184+
170185
{{< configOption
171186
name="url"
172-
type="url"
173-
description="Website URL of the organization."
174-
example="`https://opentermsarchive.org/`"
187+
type="uri"
188+
description="URL to the entity's website"
189+
example="https://opentermsarchive.org/"
190+
required=false
175191
>}}
176192
177193
{{< configOption
178194
name="logo"
179-
type="url"
180-
description="URL to the organization's logo. Optimized PNG transparent image (min width 240px)."
181-
example="`https://opentermsarchive.org/images/logo/logo-open-terms-archive-black.png`"
195+
type="uri"
196+
description="URL to the entity's logo. Optimized PNG transparent image (minimum width 240px)."
197+
example="https://opentermsarchive.org/images/logo/logo-open-terms-archive-black.png"
198+
required=false
182199
>}}
183200
184201
{{< configOption
185202
name="roles"
186-
type="string"
187-
description="Roles of the entity within the governance, see [collection governance]({{< relref \"collections/reference/governance\" >}})."
203+
type="array of strings"
204+
description="Roles of the entity within the governance, see [collection governance](https://docs.opentermsarchive.org/collections/reference/governance/)"
188205
allowedValues="`host`, `administrator`, `curator`, `maintainer`, `sponsor`"
206+
example="[host, administrator]"
189207
required=true
190208
>}}

‎themes/opentermsarchive/layouts/shortcodes/configOption.html

+8-1
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,14 @@
1212
<div class="config-option-default"><span>Default:</span>{{ .Get "default" | markdownify}}</div>
1313
{{ end }}
1414
{{ if .Get "example" }}
15-
<div class="config-option-example"><span>Example:</span>{{ .Get "example" | markdownify }}</div>
15+
<div class="config-option-example"><span>Example:</span>
16+
{{ $example := .Get "example" }}
17+
{{ if not (strings.Contains $example "\n") }}
18+
<code>{{ $example | markdownify }}</code>
19+
{{ else }}
20+
{{ $example | markdownify }}
21+
{{ end }}
22+
</div>
1623
{{ end }}
1724
{{ if .Get "allowedValues" }}
1825
<div class="config-option-allowed-values"><span>Allowed values:</span>{{ .Get "allowedValues" | markdownify }}</div>

0 commit comments

Comments
 (0)