Format & Governance

  • JSON, Schema.org Dataset + DefinedTerm / Product, served at stable URLs.
  • Build-time static generation (MkDocs); no runtime database in Phase 1.
  • Never expose sensitive or proprietary data.
  • Data changes require source traceability (termCode / reference fields).

License & versioning

  • Every dataset is licensed CC BY-SA 4.0 (share-alike, attribution required) and carries a license, version, dateModified, and changelog field.
  • Bump the minor version on any entity or structure change; record the change in changelog.

Evidence level

Every source object carries an evidenceLevel field, assigned by source nature:

Tier Label Source nature
Tier 1 Scientific / Government government checklists and regulatory lists (e.g. CITES)
Tier 2 Academic / Museum / Institutional botanical and taxonomic institutions (e.g. GBIF, Flora of China / eFloras)
Tier 3 Historical primary source classical Chinese texts (e.g. 本草綱目 / 香乘 on Wikisource)
Tier 4 Industry / Trade terminology trade and industry sources
Tier 5 Traditional knowledge traditional-knowledge sources
Tier 6 Editorial synthesis this site's own editorial pages

Main-site connection

  • Every ingredient entity carries a canonical url pointing at its human-readable page on the main site (https://incenseherbs.com/ingredients/<termCode>/).
  • The main site links back through sameAs to the data entity anchor (https://data.incenseherbs.com/ingredients/#<termCode>).
  • The data site holds structured facts, relationships and evidence; the main site holds the detailed explanation. No full-article duplication between the two.

Source status

  • Every source is a citation object { type, title, url, accessed, evidenceLevel }.
  • Source URLs must be on the allow-list (efloras.org / gbif.org / wikisource.org / checklist.cites.org / data.incenseherbs.com / incenseherbs.com / schema.org); the license field is the only exception (creativecommons.org).

CSV distribution

  • Every dataset also ships as a flat CSV distribution package, generated from the JSON source by scripts/export_csv.py — no new fact is introduced.
  • CSV columns flatten the mainEntity array with Chinese and English names side by side (name_zh / name_en) plus each dataset's additionalProperty values as columns.
  • Files are UTF-8 with a BOM so Excel opens them directly; relationships.csv is an edge list (one row per relation).
  • CSVs are regenerated on every mkdocs build into site/downloads/*.csv (served from data.incenseherbs.com/downloads/).

Entity pages & retrieval index

docs/entities/ is auto-generated by scripts/generate-entity-pages.py from datasets/*.json (single source of truth). Do not edit by hand.

  • One page per entity termCode: /entities/<termCode>/
  • Entity datasets: ingredients, aroma, materials, techniques, forms, comparisons (205 pages; shared termCodes merge into a single page)
  • terminology keeps its anchor index on the terminology page
  • Each page: entity-level JSON-LD (DefinedTerm) → Claim & Evidence → Attributes → Relationships (resolvable links only) → main-site link
  • Retrieval index: entities/index.json (machine-readable ItemList)
  • check-consistency.py verifies: no orphan pages, no missing pages, no broken /entities/ links, index count == page count

Deprecation

  • To retire an entity without deleting it, set "deprecated": true on the entity.
  • To replace an entity, point the old one at its successor with "supersededBy": "<termCode>".
  • Deprecated entities remain resolvable at their stable termCode; they are excluded from new relationships.