XML Markup Practices
Application skill for Google XML Document Format Style Guide (archived awesome-guidelines capsules). For XHTML/HTML page markup, load frontend-markup-practices. For ODF/protobuf-generated XML, follow those format rules.
Core Principle
Machine XML quality is schema-first reuse with lowerCamelCase names and element/attribute discipline, no mixed content, typed literals, UTF-8 instances validated against RELAX NG.
When to Use / NOT
- Designing config/feed/RPC XML formats, RELAX NG schemas, instance samples.
- Reviewing namespace URIs, naming, element-vs-attribute choices, serialization.
NOT when:
- XHTML/HTML rich text, use HTML/CSS guides.
- ODF or protobuf-translated XML, host format wins.
- JSON API payloads, use
json-api-practices.
Workflow
- Schema/namespaces, reuse, RELAX NG, xmlns (
xml-style-schema-namespaces.md).
- Naming/values, lowerCamelCase, dates, key-value (
xml-style-naming-values.md).
- Elements/attributes, mixed-content ban, tradeoffs (
xml-style-elements-attributes.md).
- Instances/verify, UTF-8, pretty-print, validate (
xml-style-instances-verify.md).
- Verify,
xmllint --relaxng (or project validator) on changed schema/samples.
Red Flags
- Greenfield format without reuse review
- Venetian Blind RELAX NG schema style
- Namespace-free new element names
- Single-letter namespace prefix
- PascalCase or snake_case XML names
- Mixed text and child elements in machine formats
- Useless wrapper around repeating siblings
- Attribute order assumed by consumers
- More than ~10 attributes without child grouping
- Multiline significant text in attributes
- Boolean flags instead of extensible enums
1/0 boolean tokens- Non-RFC 3339 date/time literals
- Custom mini-language embedded in values
- Raw binary without Base64
- Comments carrying required protocol data
- Custom entity declarations beyond XML five
- Hand-rolled parser assuming pretty-print shape
- Random attribute/element soup
- Applying rules to XHTML body content
- Instance PR without schema validation
Verification
- RELAX NG / XSD validates sample instances
xmllint --noout on changed .xml- Root default namespace + stable prefix map check
- lowerCamelCase name audit on new symbols
- Capsule checklist on element-vs-attribute choices
References
awesome-guidelines/references/xml-style-learning-note.mdawesome-guidelines/references/xml-style-schema-namespaces.mdawesome-guidelines/references/xml-style-naming-values.mdawesome-guidelines/references/xml-style-elements-attributes.mdawesome-guidelines/references/xml-style-instances-verify.md
1---2name: xml-markup-practices3description: Use when designing or reviewing machine-readable XML formats, reuse-first schemas, RELAX NG namespaces, lowerCamelCase names, element/attribute rules, UTF-8 instances, and xmllint/RNG validation in CI.4---56# XML Markup Practices78Application skill for Google XML Document Format Style Guide (archived `awesome-guidelines` capsules). For XHTML/HTML page markup, load `frontend-markup-practices`. For ODF/protobuf-generated XML, follow those format rules.910## Core Principle1112Machine XML quality is **schema-first reuse with lowerCamelCase names and element/attribute discipline**, no mixed content, typed literals, UTF-8 instances validated against RELAX NG.1314## When to Use / NOT1516- Designing config/feed/RPC XML formats, RELAX NG schemas, instance samples.17- Reviewing namespace URIs, naming, element-vs-attribute choices, serialization.1819**NOT when:**2021- XHTML/HTML rich text, use HTML/CSS guides.22- ODF or protobuf-translated XML, host format wins.23- JSON API payloads, use `json-api-practices`.2425## Workflow26271. **Schema/namespaces**, reuse, RELAX NG, xmlns (`xml-style-schema-namespaces.md`).282. **Naming/values**, lowerCamelCase, dates, key-value (`xml-style-naming-values.md`).293. **Elements/attributes**, mixed-content ban, tradeoffs (`xml-style-elements-attributes.md`).304. **Instances/verify**, UTF-8, pretty-print, validate (`xml-style-instances-verify.md`).315. **Verify**, `xmllint --relaxng` (or project validator) on changed schema/samples.3233## Red Flags3435- Greenfield format without reuse review36- Venetian Blind RELAX NG schema style37- Namespace-free new element names38- Single-letter namespace prefix39- PascalCase or snake_case XML names40- Mixed text and child elements in machine formats41- Useless wrapper around repeating siblings42- Attribute order assumed by consumers43- More than ~10 attributes without child grouping44- Multiline significant text in attributes45- Boolean flags instead of extensible enums46- `1`/`0` boolean tokens47- Non-RFC 3339 date/time literals48- Custom mini-language embedded in values49- Raw binary without Base6450- Comments carrying required protocol data51- Custom entity declarations beyond XML five52- Hand-rolled parser assuming pretty-print shape53- Random attribute/element soup54- Applying rules to XHTML body content55- Instance PR without schema validation5657## Verification5859- RELAX NG / XSD validates sample instances60- `xmllint --noout` on changed `.xml`61- Root default namespace + stable prefix map check62- lowerCamelCase name audit on new symbols63- Capsule checklist on element-vs-attribute choices646566## References6768- `awesome-guidelines/references/xml-style-learning-note.md`69- `awesome-guidelines/references/xml-style-schema-namespaces.md`70- `awesome-guidelines/references/xml-style-naming-values.md`71- `awesome-guidelines/references/xml-style-elements-attributes.md`72- `awesome-guidelines/references/xml-style-instances-verify.md`
ryan-brosas