Skip to content

Commit 6fb4c1f

Browse files
NdpntNdpnt
committed
Improve metadata documentation
1 parent 0305574 commit 6fb4c1f

File tree

2 files changed

+190
-72
lines changed

2 files changed

+190
-72
lines changed

‎content/collections/reference/metadata.en.md‎

Lines changed: 0 additions & 72 deletions
This file was deleted.

‎content/collections/reference/metadata.md‎

Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
---
2+
title: Metadata
3+
weight: 1
4+
---
5+
6+
# Collection metadata
7+
8+
This reference documentation details all available metadata fields that can be specified in a collection's metadata file.
9+
10+
## Fields
11+
12+
{{< configOption
13+
name="id"
14+
type="string"
15+
description="Unique identifier derived from name (acronyms, dash-separated)"
16+
example="`pga`"
17+
required=true
18+
>}}
19+
20+
{{< configOption
21+
name="name"
22+
type="string"
23+
description="Display name of the collection (max 3 words)"
24+
example="`Platform Governance Archive`"
25+
required=true
26+
>}}
27+
28+
{{< configOption
29+
name="tagline"
30+
type="string"
31+
description="Concise description of collection topic"
32+
example="`Major global social media services`"
33+
required=true
34+
>}}
35+
36+
{{< configOption
37+
name="languages"
38+
type="Array of strings"
39+
description="[ISO 639 language codes](https://en.wikipedia.org/wiki/ISO_639) allowed in collection"
40+
example="`[en, fr, de]`"
41+
required=true
42+
>}}
43+
44+
{{< configOption
45+
name="jurisdictions"
46+
type="Array of strings"
47+
description="[ISO 3166-2 country codes](https://en.wikipedia.org/wiki/ISO_3166-2) for covered jurisdictions"
48+
example="`[EU]`"
49+
required=true
50+
>}}
51+
52+
{{< configOption
53+
name="description"
54+
type="string"
55+
description="Detailed description of the collection"
56+
example=`The **Platform Governance Archive** (PGA) collection tracks the terms of major global social media services.
57+
58+
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).
59+
60+
This initiative offers researchers, journalists and citizens the tools to analyze how platforms structure and regulate communication and interaction in our societies.
61+
62+
It also aims to promote greater transparency and accountability of these powerful digital services.`
63+
>}}
64+
65+
{{< configOption
66+
name="dataset"
67+
type="url"
68+
description="URL to released versions dataset"
69+
example="`https://github.com/OpenTermsArchive/pga-versions/releases`"
70+
>}}
71+
72+
{{< configOption
73+
name="declarations"
74+
type="url"
75+
description="URL to declarations repository"
76+
example="`https://github.com/OpenTermsArchive/pga-declarations`"
77+
>}}
78+
79+
{{< configOption
80+
name="versions"
81+
type="url"
82+
description="URL to versions repository"
83+
example="`https://github.com/OpenTermsArchive/pga-versions`"
84+
>}}
85+
86+
{{< configOption
87+
name="snapshots"
88+
type="url"
89+
description="URL to snapshots repository"
90+
example="`https://github.com/OpenTermsArchive/pga-snapshots`"
91+
>}}
92+
93+
{{< configOption
94+
name="logo"
95+
type="url"
96+
description="URL to the collection's logo. Optimized PNG transparent image (min width 240px)"
97+
example="`https://opentermsarchive.org/images/collections/pga.png`"
98+
>}}
99+
100+
{{< configOption
101+
name="donations"
102+
type="url"
103+
description="URL to the donations page"
104+
example="`https://opencollective.com/opentermsarchive`"
105+
>}}
106+
107+
{{< configOption
108+
name="trackingPeriods"
109+
type="array of tracking periods objects"
110+
description="Tracking periods object, see [Tracking periods](#tracking-periods) section"
111+
>}}
112+
113+
{{< configOption
114+
name="governance"
115+
type="array of entity objects"
116+
description="Entity object, see [Entity](#entity) section"
117+
>}}
118+
119+
---
120+
121+
### Tracking periods
122+
123+
{{< configOption
124+
name="startDate"
125+
type="date"
126+
description="The date when tracking started (ISO 8601 format: YYYY-MM-DD)"
127+
example="`2023-01-01`"
128+
required=true
129+
>}}
130+
131+
{{< configOption
132+
name="endDate"
133+
type="date"
134+
description="The date when tracking ended or will end. If not specified, tracking is ongoing."
135+
example="`2024-12-31`"
136+
>}}
137+
138+
{{< configOption
139+
name="schedule"
140+
type="string"
141+
description="A [cron expression](https://en.wikipedia.org/wiki/Cron#Cron_expression) that defines the tracking frequency"
142+
example="`0 0 * * *`"
143+
required=true
144+
>}}
145+
146+
{{< configOption
147+
name="serverLocation"
148+
type="string"
149+
description="The geographic location of the tracking server (city name, ISO 3166-2 country code)"
150+
example="`London, GB`"
151+
required=true
152+
>}}
153+
154+
---
155+
156+
### Entity
157+
158+
{{< configOption
159+
name="name"
160+
type="string"
161+
description="Name of the organization"
162+
example="`Open Terms Archive`"
163+
required=true
164+
>}}
165+
166+
{{< configOption
167+
name="url"
168+
type="url"
169+
description="Website URL of the organization"
170+
example="`https://opentermsarchive.org/`"
171+
>}}
172+
173+
{{< configOption
174+
name="logo"
175+
type="url"
176+
description="URL to the organization's logo. Optimized PNG transparent image (min width 240px)"
177+
example="`https://opentermsarchive.org/images/logo/logo-open-terms-archive-black.png`"
178+
>}}
179+
180+
{{< configOption
181+
name="roles"
182+
type="string"
183+
description="Roles of the entity within the governance"
184+
allowedValues="`host`, `administrator`, `curator`, `maintainer`, `sponsor`"
185+
required=true
186+
>}}
187+
188+
---
189+
190+
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).

0 commit comments

Comments
 (0)