Skip to content

Sync default Data Use taxonomy with the restructured explorer taxonomy - #205

Draft
jwrosewell wants to merge 1 commit into
IABTechLab:mainfrom
jwrosewell:sync-code-taxonomy-to-restructured-data-uses
Draft

Sync default Data Use taxonomy with the restructured explorer taxonomy#205
jwrosewell wants to merge 1 commit into
IABTechLab:mainfrom
jwrosewell:sync-code-taxonomy-to-restructured-data-uses

Conversation

@jwrosewell

Copy link
Copy Markdown

Draft / proposal for discussion. The source docs CSV is a work in progress, so several points below need a maintainer decision before this should be considered ready. Happy to adjust scope or split it up.

Summary

The Data Use taxonomy is currently in a split state. PR #196 restructured the docs taxonomy in mkdocs/docs/csv/data_uses.csv to the new top levels (necessary, functional, analytics, advertising_marketing, disclosure) and added tcf/mspa columns, but the code source of truth and the artifacts generated from it were left on the old Fides 3.0 structure:

  • src/fideslang/default_taxonomy/data_uses.py
  • data_files/data_uses.{yml,json,csv}
  • src/fideslang/gvl/gvl_data_use_mapping.json

So a consumer reading the published package still gets marketing.advertising.first_party.targeted, essential.*, third_party_sharing, and so on, rather than the restructured Data Uses the explorer shows. This PR brings the code in line with the docs.

What changed

  • default_taxonomy/data_uses.py regenerated directly from mkdocs/docs/csv/data_uses.csv so the code matches the docs, now 62 Data Uses across the five new top levels.
  • data_files/data_uses.{yml,json,csv} regenerated via scripts/export_default_taxonomy.py.
  • gvl/gvl_data_use_mapping.json remapped from the old keys to the new ones (for example marketing.advertising.* -> advertising_marketing.*, essential.* -> necessary.*, analytics.reporting.* -> analytics.ad_reporting.*).
  • Tests updated for the new keys and count. The full suite passes (137 tests).

Open questions for maintainers

  1. Top-level naming. The restructure is sometimes described with a top-level operational, but the CSV models this as necessary.operations (nested) plus a separate functional top level. This PR follows the CSV. Please confirm the intended top levels.
  2. Two TCF purposes have no equivalent in the restructured taxonomy and are mapped to an empty list (flagged): purpose 1 "Store and/or access information on a device" and purpose 11 "Use limited data to select content".
  3. A few GVL mappings are best-effort where the old -> new correspondence is not one to one and should be confirmed: purpose 6 -> advertising_marketing.personalize.content, purpose 10 -> necessary.operations.improve.
  4. Source-CSV data-quality fixes made so the taxonomy validates (descriptions must be present and unique), flagged rather than changed silently:
    • Four parent nodes had blank descriptions (necessary, analytics.ad_reporting, analytics.reporting, advertising_marketing.personalize); short descriptions were added.
    • Two uses shared an identical description (measure_ad_performance and ad_delivery_and_targeting); the latter was given a distinct one.
    • Name typos remain in the CSV (for example "Quality Assuarance", "Performance Optimmization"); these were mirrored verbatim and left for a separate cleanup.
  5. Where should tcf/mspa live? They exist only as hand-maintained columns in the docs CSV today. scripts/export_default_taxonomy.py copies data_files/data_uses.csv over the docs CSV, which would drop those columns, so this PR intentionally does not overwrite the docs CSV. That leaves the docs CSV and the generated data_files CSV slightly out of step. Modelling tcf/mspa on DataUse so the docs CSV can be generated would be a cleaner long-term fix, but is out of scope here.

Context

This came out of adopting the Data Use taxonomy as the permission vocabulary for a Trusted Server permission model (IABTechLab/trusted-server#838). The immediate need was a single, consistent, machine-readable taxonomy to build against, which surfaced the split between the code and the docs.

The docs Data Use taxonomy (mkdocs/docs/csv/data_uses.csv) was restructured
to the new top levels (necessary, functional, analytics, advertising_marketing,
disclosure) in IABTechLab#196, but the code source of truth and generated artifacts were
left on the old Fides 3.0 structure. This brings them into line:

- Regenerate src/fideslang/default_taxonomy/data_uses.py from the docs CSV
  (now 62 data uses across the five new top levels).
- Regenerate data_files/data_uses.{yml,json,csv} via
  scripts/export_default_taxonomy.py.
- Remap src/fideslang/gvl/gvl_data_use_mapping.json from the old data-use keys
  to the new ones.
- Update tests for the new keys and count.

Open questions for maintainers are called out in the pull request description
(top-level naming, source-CSV data-quality fixes, TCF/MSPA modelling, and two
TCF purposes with no equivalent in the restructured taxonomy).

Signed-off-by: James Rosewell <james@51degrees.com>
@jwrosewell
jwrosewell force-pushed the sync-code-taxonomy-to-restructured-data-uses branch from bcd323b to 3327b5d Compare August 4, 2026 12:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant