Skip to content

Commit 161c437

Browse files
NdpntNdpnt
committed
Update metadata doc
1 parent 491dfed commit 161c437

File tree

2 files changed

+126
-61
lines changed

2 files changed

+126
-61
lines changed

‎content/collections/create.en.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ You are considering creating a new collection to track terms with Open Terms A
99

1010
## Define metadata
1111

12-
First of all, define the [metadata]({{< relref "collections/metadata" >}}) of the collection you would like to create.
12+
First of all, define the [metadata]({{< relref "collections/metadata" >}}) of the collection you would like to create and keep them ready to be used when setting up the repositories.
1313

1414
## Check existing collections
1515

@@ -80,6 +80,10 @@ Issues labels will be added by the engine as problems are encountered when track
8080

8181
- Update the README file with proper metadata: topic, maintainers, jurisdictions, languages…
8282

83+
#### Update metadata
84+
85+
- Update the metadata file `metadata.yml` with the collection metadata you defined earlier.
86+
8387
### Snapshots
8488

8589
Create the snapshots repository by using the [`demo-snapshots` repository](https://github.com/OpenTermsArchive/demo-snapshots) as template:

‎content/collections/metadata.en.md‎

Lines changed: 121 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -5,63 +5,124 @@ weight: 1
55

66
# Collection metadata
77

8-
A collection is defined by the following metadata.
9-
10-
## Description
11-
12-
A concise description of the collection topic.
13-
14-
### Examples
15-
16-
- Largest global social media
17-
- Most used social media in France
18-
- Dating apps
19-
- Platforms providing services to businesses
20-
21-
## Name
22-
23-
Three words maximum.
24-
25-
### Examples
26-
27-
- Platform Governance Archive
28-
- France Élections
29-
- Dating
30-
- P2B Compliance Assessment
31-
32-
## ID
33-
34-
An identifier derived from the collection name that can more easily be referenced in code. Use acronyms and replace spaces with dashes.
35-
36-
### Examples
37-
38-
- `pga`
39-
- `France-elections`
40-
- `dating`
41-
- `p2b-compliance`
42-
43-
## Language
44-
45-
The expected language of the terms in the collection.
46-
47-
### Examples
48-
49-
- `English`
50-
- `French`
51-
- `All EU languages`
52-
53-
## Jurisdiction
54-
55-
The expected jurisdiction in which the terms in the collection apply.
56-
57-
### Examples
58-
59-
- `EU`
60-
- `France`
61-
- `EEA`
62-
- `USA`
63-
- `global`
64-
65-
## Roles
66-
67-
The name, URL and logo of the entities that will take responsibility for each of the necessary governance [roles]({{< relref "collections/governance" >}}).
8+
A collection is defined by the following metadata fields:
9+
10+
| JSON Field | Type | Required | Description | Example |
11+
|------------|------|----------|-------------|---------|
12+
| `name` | string | ✓ | Display name of the collection (max 3 words) | Platform Governance Archive |
13+
| `id` | string | ✓ | Unique identifier derived from name (acronyms, dash-separated) | `pga` |
14+
| `tagline` | string | ✓ | Concise description of collection topic | Largest global social media |
15+
| `description` | string | - | Detailed context beyond tagline | Comprehensive collection of terms of service from major global social media platforms. |
16+
| `languages` | Array of strings | ✓ | ISO 639 language codes allowed in collection | `["en", "fr", "de"]` |
17+
| `jurisdictions` | Array of strings | ✓ | ISO 3166-2 country codes for covered jurisdictions | `["EU", "global"]` |
18+
| `trackingPeriods` | object | - | Information about tracking schedule | see [Tracking Periods](#tracking-periods) section |
19+
| `dataset` | url | - | URL to released versions dataset | `https://github.com/OpenTermsArchive/demo-versions/releases` |
20+
| `declarations` | url | - | URL to declarations repository | `https://github.com/OpenTermsArchive/demo-declarations` |
21+
| `versions` | url | - | URL to versions repository | `https://github.com/OpenTermsArchive/demo-versions` |
22+
| `snapshots` | url | - | URL to snapshots repository | `https://github.com/OpenTermsArchive/demo-snapshots` |
23+
| `logo` | url | - | URL to collection logo | `https://opentermsarchive.org/images/collections/demo.png` |
24+
| `governance` | object | - | Governance information | see [Governance](#governance) section |
25+
| `donation` | url | - | URL to donation page | `https://opentermsarchive.org/donate` |
26+
27+
## Tracking periods
28+
29+
Information about when and how terms are tracked:
30+
31+
| JSON Field | Type | Required | Description | Example |
32+
|------------|------|----------|-------------|---------|
33+
| `startDate` | date | - | Date when tracking began | `2023-01-01` |
34+
| `endDate` | date | - | Date when tracking ended/will end. No end date means tracking is ongoing. | `2024-12-31` |
35+
| `schedule` | string | - | Cron expression defining tracking frequency | `0 0 * * *` (daily at midnight) |
36+
| `serverLocation` | string | - | Geographic location of tracking server | `London, GB` |
37+
38+
**Example:**
39+
40+
```yaml
41+
trackingPeriods:
42+
startDate: 2023-01-01
43+
endDate: 2024-12-31
44+
schedule: "0 0 * * *"
45+
serverLocation: London, GB
46+
```
47+
48+
## Governance
49+
50+
Organizations responsible for collection roles:
51+
52+
| JSON Field | Type | Required | Description | Example |
53+
|------------|------|----------|-------------|---------|
54+
| `hosts` | Array of objects | - | Organizations hosting the collection | see [Organization](#organization) section |
55+
| `administrators` | Array of objects | - | Organizations managing the collection | see [Organization](#organization) section |
56+
| `curators` | Array of objects | - | Organizations curating the content | see [Organization](#organization) section |
57+
| `maintainers` | Array of objects | - | Organizations maintaining the technical aspects | see [Organization](#organization) section |
58+
| `sponsors` | Array of objects | - | Organizations providing support | see [Organization](#organization) section |
59+
60+
## Organization
61+
62+
Each organization in the governance roles is defined by the following fields:
63+
64+
| JSON Field | Type | Required | Description | Example |
65+
|------------|------|----------|-------------|---------|
66+
| `name` | string | - | Name of the organization | `Open Terms Archive` |
67+
| `url` | url | - | Website URL of the organization | `https://opentermsarchive.org/` |
68+
| `logo` | url | - | URL to the organization's logo | `https://opentermsarchive.org/images/logo/logo.png` |
69+
70+
**Example:**
71+
72+
```yaml
73+
governance:
74+
administrators:
75+
- name: Open Terms Archive
76+
url: https://opentermsarchive.org/
77+
logo: https://opentermsarchive.org/images/logo/logo-open-terms-archive-black.png
78+
curators: []
79+
maintainers: []
80+
hosts: []
81+
sponsors: []
82+
```
83+
84+
**Complete metadata example:**
85+
86+
```yaml
87+
id: demo
88+
name: Demo
89+
tagline: Services needed to operate the Open Terms Archive engine
90+
description: This demo collection serves as a reference implementation...
91+
dataset: https://github.com/OpenTermsArchive/demo-versions/releases
92+
declarations: https://github.com/OpenTermsArchive/demo-declarations
93+
versions: https://github.com/OpenTermsArchive/demo-versions
94+
snapshots: https://github.com/OpenTermsArchive/demo-snapshots
95+
logo: https://opentermsarchive.org/images/collections/demo.png
96+
languages:
97+
- en
98+
jurisdictions:
99+
- EU
100+
termsTracked: 100
101+
servicesTracked: 50
102+
trackingPeriods:
103+
startDate: 2023-01-01
104+
endDate: 2024-12-31
105+
schedule: "0 0 * * *"
106+
serverLocation: EU-WEST-1
107+
governance:
108+
hosts:
109+
- name: Ministry for Europe and Foreign Affairs
110+
url: https://www.diplomatie.gouv.fr/en/
111+
logo: https://opentermsarchive.org/images/contributors/meae.png
112+
administrators:
113+
- name: Open Terms Archive
114+
url: https://opentermsarchive.org/
115+
logo: https://opentermsarchive.org/images/logo/logo-open-terms-archive-black.png
116+
curators:
117+
- name: Open Terms Archive
118+
url: https://opentermsarchive.org/
119+
logo: https://opentermsarchive.org/images/logo/logo-open-terms-archive-black.png
120+
maintainers:
121+
- name: Open Terms Archive
122+
url: https://opentermsarchive.org/
123+
logo: https://opentermsarchive.org/images/logo/logo-open-terms-archive-black.png
124+
sponsors:
125+
- name: Ministry for Europe and Foreign Affairs
126+
url: https://www.diplomatie.gouv.fr/en/
127+
logo: https://opentermsarchive.org/images/contributors/meae.png
128+
```

0 commit comments

Comments
 (0)