Tracking new terms

Tracking terms is done by declaring them and the service they are associated with. Such a declaration is achieved by editing JSON files in the declarations folder.

Before adding new terms, open the declarations folder and check if the service you want to track terms for is already declared. If a JSON file with the name of the service is already present, you can jump straight to the Terms reference. Otherwise, keep reading!

Declaring a new service

Before declaring a service, you will need to choose the service name and service ID. The service ID will be the name of the JSON file in which the service will be declared. It is a normalised version of the service name.

Service name

The service name is exposed to end users. It should reflect as closely as possible the official service name, as referenced in the terms or “about” pages, so that it can be recognised easily and unambiguously.

• The service name should be the one used by the service itself, no matter the alphabet, UTF symbols, spaces, and casing.
  • Example: eBay.
  • Example: hi5.
  • Example: LINE.
  • Example: App Store.
  • Example: туту.ру (Cyrillic).
  • Example: 抖音短视频 (Simplified Chinese characters).
• Domain name extensions (TLDs) are allowed when they are part of the official service name.
  • Example: Booking.com.
  • Example: historielærer.dk.
• Service names can be prefixed by the provider name, separated by a space, when it would otherwise be too generic or ambiguous.
  • Example: Ads (by Facebook) → Facebook Ads.
  • Example: Analytics (by Google) → Google Analytics.
  • Example: Firebase (by Google) → Firebase.
  • Example: App Store (by Apple) → App Store.

If you have a hard time finding the service name, check out the practical guidelines to find the service name, and feel free to mention your uncertainties in the pull request! We will help you improve the service name if necessary 🙂

Service ID

The service ID is exposed to developers. It should be easy to handle with scripts and other tools.

• Non-ASCII characters are not supported. Service IDs are derived from the service name by normalising it into ASCII.
  • Example: RTÉ → RTE.
  • Example: historielærer.dk → historielaerer.dk.
  • Example: туту.ру → tutu.ru.
  • Example: 抖音短视频 → Douyin.
• Punctuation is supported, except characters that have meaning at filesystem level (:, /, \). These are replaced with a dash (-). The dot (.) is supported, but the service ID cannot be solely . or .. as these have specific meanings in the filesystem.
  • Example: Booking.com → Booking.com.
  • Example: Yahoo! → Yahoo!.
  • Example: re:start → re-start.
  • Example: we:// → we---.
• Capitals and spaces are supported. Casing and spacing are expected to reflect the official service name casing and spacing.
  • Example: App Store → App Store.
  • Example: DeviantArt → DeviantArt.

If you have a hard time defining the service ID, check out the practical guidelines to derive the ID from the service name, and feel free to mention your uncertainties in the pull request! We will help you improve the service ID if necessary 🙂

More details on the ID and naming constraints and recommendations can be found in the relevant decision record.

Service declaration

Once you have the service name and the service ID, create a JSON file in the declarations folder named after the ID of the service you want to add, with the following structure:

{
  "name": "<service name>",
  "documents": {}
}

Within the documents JSON object, you will now declare terms.