Metadata
Metadata in a documentation set is useful only when it is consistent. A policy defines the fields that topics must contain. The editor audits the content against the policy and fills in missing fields without changing the rest of the prolog.
Where the policy lives
The required-metadata policy is part of the project configuration, in .dogsbay/config.xml. Because it is a file in the project, it is shared with everyone who clones it and changes with the content. For the rule attributes and field names, see Project configuration.
You can point at a different policy for one run with --policy.
Auditing
dogsbay-xml metadata-audit . --map audacity-guide.ditamapThe command reports where required fields are missing or contain a value that the policy does not allow. It exits with a nonzero status on any error-level violation, so it works as a pipeline gate.
Use --scope to audit something other than a map's publication set, such as a glob or the project root.
Filling in what is missing
metadata-set applies changes in bulk and preserves the fields it is not asked to touch.
dogsbay-xml metadata-set . --map audacity-guide.ditamap \
--fill audience=user --dry-runThe four operations differ in a way worth getting right:
| Option | Effect |
|---|---|
--fill | Set the field only where it is absent. Existing values are left alone. |
--set | Overwrite the field everywhere in scope. |
--append | Add a value to a list field, keeping what is there. |
--remove | Remove a field, or one value from a list field. |
Repeat an option to change several fields in one pass.
metadata-set writes unless you pass --dry-run. That is the opposite of the refactoring commands, which do nothing until you pass --apply. Check with --dry-run first on a scope you have not touched before.
Enforcing the policy outside the editor
The same policy can be compiled to ISO Schematron, so a build system that has no DogsBay XML can still check it:
dogsbay-xml metadata-export-schematron . --output metadata-policy.schRun the result anywhere Schematron runs, including here:
dogsbay-xml schematron-project . metadata-policy.schA useful order
- Audit before you change anything
metadata-audittells you the size of the problem. - Fill the gaps Use
metadata-set --fillfor fields with a standard default. Check with--dry-runfirst. - Fix the rest by hand What is left usually needs a human, which is the point of separating fill from set.
- Gate it Add
metadata-auditto the pipeline so the gap does not reopen.