---
title: Vocabulary Tag
description: Lexicon reference for org.hypercerts.vocab.tag, a reusable term for classifying Hypercerts records, used today by collections and features.
---

# Vocabulary Tag

`org.hypercerts.vocab.tag`

## Overview

A vocabulary tag is one term in a shared classification vocabulary, such as a land-cover class, a zone role, or a methodology. Instead of typing "mangrove" into a free-text field, a record points to a published tag that says what "mangrove" means, who defined it, and how it relates to other terms.

Because each tag is a record with its own publisher and AT-URI, two tags called "restoration" from different organizations stay distinct, and an application can inspect the intended meaning instead of guessing from the label. For the concepts behind it, see [Describing and Classifying Work](/core-concepts/cel-work-scopes) in the Guide.

## How it's used

- **A curator publishes a vocabulary.** A funder, registry, standards body, or community publishes a set of tag records, each with a `category` (the classification axis), a `key`, a `name`, and a definition in `description`. Any account can publish tags; there is no central registry.
- **Records reference tags to classify themselves.** [Collections](/lexicons/hypercerts-lexicons/collection) and [features](/lexicons/hypercerts-lexicons/feature) carry a `tags` array of strong references to tag records. A directory can then group projects by subject, or a funder can find land areas of a given type.
- **Terms form a hierarchy.** `broader` links a term to one or more directly broader terms, so "mangrove" can sit under "coastal wetland" and "forest" at the same time.
- **Terms are retired, not deleted.** A curator sets `status` to `deprecated` and points `supersededBy` at the replacement. Records that used the old term keep their references, and applications can show the replacement alongside it.
- **External vocabularies line up.** `sameAs` lists URIs of exactly equivalent concepts elsewhere (for example ENVO or IUCN ecosystem types), so data keyed by an external vocabulary can be joined to Hypercerts records.

Vocabulary tags classify records so people can find them. They are separate from [work-scope tags](/lexicons/hypercerts-lexicons/work-scope), which describe what an activity covers.

## Schema

**Record key:** `any` · **Lexicon version:** 1.4.1 · [View the schema](https://github.com/hypercerts-org/hypercerts-lexicon/blob/v1.4.1/lexicons/org/hypercerts/vocab/tag.json)

### Required properties

| Property | Type | Description |
|---|---|---|
| `key` | string (record-key) | Stable lowercase machine identifier for this term within its publisher and category, for example boundary or mangrove. Must not contain dots, so that the recommended <category>.<key> record key remains unambiguous. `maxLength: 120` |
| `name` | string | Human-readable display name of the term. `maxLength: 200` |
| `category` | string (record-key) | The classification axis this term belongs to, for example land-cover or zone-role. One term belongs to one category; a subject may carry tags from many categories at once. Values beyond the known set are permitted. Must not contain dots, so that the recommended <category>.<key> record key remains unambiguous. `maxLength: 50` Known values: `zone-role`, `land-cover`, `ecosystem-type`, `stratum-class`, `tenure`, `methodology`, `outcome-class`, `evidence-type`. |
| `status` | string | Lifecycle status of the term: proposed (submitted, not yet governed), accepted (in active governed use), or deprecated (retired; see supersededBy). Values beyond the known set are permitted. `maxLength: 20` Known values: `proposed`, `accepted`, `deprecated`. |
| `createdAt` | string (datetime) | Client-declared timestamp when this record was originally created. |

### Optional properties

| Property | Type | Description |
|---|---|---|
| `description` | string | Definition and scope notes for the term, written so a reader outside the publishing organization can apply it consistently. `maxLength: 10000` `maxGraphemes: 1000` |
| `broader` | array of `strongRef` | Optional references to directly broader terms, forming a polyhierarchy (a term may have several broader terms). Each referenced record must conform with org.hypercerts.vocab.tag. `maxItems: 20` |
| `supersededBy` | `strongRef` | The replacement term for a deprecated term, letting consumers roll classifications forward without rewriting published records. The referenced record must conform with org.hypercerts.vocab.tag. |
| `aliases` | array of string | Alternative human-readable labels and abbreviations for search and display. Aliases carry no identity: references always point at the record, not at a label. `maxItems: 50` `item maxLength: 200` |
| `sameAs` | array of string (uri) | URIs of exactly equivalent concepts in external vocabularies, for example ENVO, IUCN GET, OSM tag conventions, or registry methodology identifiers. Exact matches only; typed broader/narrower/close mappings are a named future field. `maxItems: 20` |
| `referenceDocument` | union: [`org.hypercerts.defs#uri`](/lexicons/hypercerts-lexicons/shared-defs#uri), [`org.hypercerts.defs#smallBlob`](/lexicons/hypercerts-lexicons/shared-defs#smallblob) | A document defining or motivating this term, as a URI or an attached small blob. |
| `signatures` | [`app.certified.signature.defs#list`](/lexicons/certified-lexicons/signatures#list) | Optional cryptographic signatures attesting to this record's content. |

## Example

A land-restoration vocabulary term for mangrove land cover, published at record key `land-cover.mangrove`:

```json
{
  "$type": "org.hypercerts.vocab.tag",
  "key": "mangrove",
  "name": "Mangrove",
  "category": "land-cover",
  "description": "Intertidal forest or shrubland dominated by salt-tolerant mangrove species. Use for areas where mangrove canopy covers at least 10% of the ground, including replanted stands. Use bare-mudflat for tidal areas without woody cover.",
  "broader": [
    {
      "uri": "at://did:plc:3kzv6qm7xw2hrl5tdnyb4fae/org.hypercerts.vocab.tag/land-cover.coastal-wetland",
      "cid": "bafyreibv4hwqkz7m2xrd3ylpnc6tjsa5fqe2gkoh4wzvmu3i7db6xnlqye"
    }
  ],
  "status": "accepted",
  "aliases": ["Mangrove forest", "Mangal"],
  "sameAs": ["https://vocab.example.org/land-cover/mangrove"],
  "referenceDocument": {
    "$type": "org.hypercerts.defs#uri",
    "uri": "https://restoration-vocab.example.org/land-cover/mangrove"
  },
  "createdAt": "2026-05-14T10:20:00.000Z"
}
```

## Rules and best practices

- **Use the record key `<category>.<key>`.** The schema recommends a deterministic record key such as `land-cover.mangrove` or `zone-role.site`. Validation cannot check that the record key matches the body, so writers and indexers keep the two in agreement.
- **Keep `key` and `category` lowercase and free of dots.** Both use the `record-key` format, which permits dots and uppercase, but a dot makes the composed record key ambiguous and a case variant creates a second term that will not match the first.
- **Write a real definition.** `description` is what lets someone outside your organization apply the term consistently. A name alone rarely says where the boundary of a term lies; say what is included and, where useful, what belongs under a neighboring term.
- **Classify by reference, not by label.** A term is identified by its AT-URI. Two tags with the same `name` or a shared alias are not the same term. Use `aliases` for search, autocompletion, and display, not to decide which term a record uses.
- **Reuse before you mint.** If an existing, accepted term from a vocabulary your users recognize fits, reference it rather than copying it into your own repository. A private copy breaks the comparability that shared terms exist to provide.
- **Mark new terms as `proposed`.** `status` is required. Use `proposed` for terms that have not been through a curation process, `accepted` for terms in governed use, and `deprecated` for retired terms.
- **Publish a changed concept as a new term.** If the meaning of a term changes, create a new record, set the old one to `deprecated`, and point its `supersededBy` at the new one. Editing the definition in place silently changes what earlier classifications meant.
- **Keep `sameAs` for exact matches.** List only external concepts that mean exactly the same thing. Broader, narrower, or related concepts do not belong there.
- **A tag array is a set of facts.** All tags on a collection or feature apply at once (logical AND), with no order, weighting, or negation. Put boolean logic in a work scope instead, and don't reference the same tag twice in one array.
- **Readers pin a version and look up the current state.** A tag reference pins the version (CID) the record was classified against. To find whether a term has since been deprecated or superseded, applications resolve the term by its URI. A retired term still classifies the records that used it.
- **Hierarchy is not inheritance.** `broader` states a direct relationship. A record tagged "mangrove" has not itself asserted "coastal wetland". An application that expands a query to broader or narrower terms should make that visible to the reader.

## Related

- [Collection](/lexicons/hypercerts-lexicons/collection) and [Feature](/lexicons/hypercerts-lexicons/feature): the records that carry `tags`.
- [Work Scope](/lexicons/hypercerts-lexicons/work-scope): a separate tag system for describing what an activity covers.
- [Shared Definitions](/lexicons/hypercerts-lexicons/shared-defs): the `uri` and `smallBlob` objects used by `referenceDocument`.
- Guide: [Describing and Classifying Work](/core-concepts/cel-work-scopes), [Records That Change Over Time](/architecture/data-flow-and-lifecycle), [Finding and Reusing Information](/architecture/portability-and-scaling).