Standards Format Specification

Standards Format Specification

Every VCP standard follows a consistent structure designed to be both human-readable and AI-parseable. This specification ensures that Claude Sonnet 4.5 (the baseline target model) can follow the rules without relying on implicit knowledge.

File Location

Standards live in the standards/ root directory with a {scope}-{topic}.md naming convention:

standards/
├── manifest.json
├── scopes/
│   ├── core.json
│   ├── web-backend.json
│   └── ...
├── core-security.md
├── core-architecture.md
├── web-frontend-security.md
├── compliance-gdpr.md
└── ...

YAML Frontmatter

Every standard starts with YAML frontmatter:

---
id: core-security
title: Security
scope: core
severity: critical
tags:
  - security
  - owasp
  - cwe
  - input-validation
  - authentication
  - cryptography
references:
  - title: "OWASP Top 10:2025"
    url: "https://owasp.org/Top10/2025/"
  - title: "CWE Top 25"
    url: "https://cwe.mitre.org/top25/"
---

Required Fields

Field	Type	Description
id	string	Unique identifier in {scope}-{topic} format
title	string	Human-readable name
scope	string	One of: core, web-frontend, web-backend, database, mobile, desktop, cli, devops, compliance
severity	string	One of: critical, high, medium, low
tags	string[]	Searchable tags — include CWE IDs, OWASP references, and topic keywords

Optional Fields

Field	Type	Description
references	array	External references with title and url

Required Sections

Every standard must contain these sections in order:

1. Principle

The WHY — 1-3 sentences explaining the core principle and why it matters.

## Principle

Every input is hostile until proven otherwise. Validate at the boundary,
not where you happen to use the data. This prevents entire categories of
vulnerabilities rather than playing whack-a-mole with individual bugs.

2. Rules

Numbered, actionable, imperative statements. Each rule should be unambiguous and testable. Include CWE references where applicable.

## Rules

1. **Validate all input at system boundaries.** Check type, length, format,
   and range before the data enters your application logic. (CWE-20)

2. **Use parameterized queries for all database access.** Never concatenate
   user input into SQL strings. (CWE-89)

3. **Encode output for the target context.** HTML-encode for HTML, URL-encode
   for URLs, JavaScript-encode for inline scripts. (CWE-79)

Rules must be:

• Imperative: "Do X" not "Consider X"
• Specific: "Use parameterized queries" not "Be careful with SQL"
• Testable: Someone (human or AI) can check if the rule is followed
• Self-contained: Understandable without reading other sections

3. Patterns

Code examples showing Do This and Not This with explanations.

Each pattern section should:

• Show the correct (safe) approach first
• Show the incorrect (dangerous) approach second
• Explain WHY the incorrect approach is dangerous
• Use realistic, recognizable code snippets

See any existing standard in standards/ (e.g., core-security.md) for examples of the pattern format.

4. Exceptions

When deviation from the rules is acceptable, and what safeguards are needed.

## Exceptions

- **Trusted internal tools** with no external input may skip input validation,
  but must document the trust boundary.
- **Generated DDL in migration scripts** may use string building for schema
  changes since these don't process user input at runtime.

5. Cross-References

Links to related VCP standards and external resources.

## Cross-References

- [VCP Architecture Standard](core-architecture.md) — Layer boundaries
  determine where validation occurs
- [VCP Error Handling Standard](core-error-handling.md) — How to handle
  validation failures

Writing Guidelines

Be AI-Parseable

• Use consistent heading levels (## for sections, ### for subsections)
• Use numbered lists for rules (AI can reference "Rule 3")
• Use bold for rule titles (extracted by regex /^\d+\.\s+\*\*(.+?)\*\*/gm)
• Use code blocks with language tags for examples

Be Principled, Not Prescriptive

• Explain WHY before WHAT
• Allow alternatives that satisfy the principle
• Don't mandate specific libraries or tools (unless there's a security reason)

Target Claude Sonnet 4.5

• If a rule requires a more capable model to interpret correctly, the rule isn't specific enough
• Don't rely on implicit knowledge — spell it out
• Provide code examples for any non-obvious pattern

Be Actionable

• "Do X" not "Consider X"
• "Use parameterized queries" not "Be careful with database access"
• Every rule should be checkable in a code review

Manifest Registration

After creating a standard, add it to the appropriate scope manifest in standards/scopes/. For example, to add a standard to the core scope, edit standards/scopes/core.json:

{
  "scope": "core",
  "standards": [
    { "id": "core-security", "url": "https://raw.githubusercontent.com/Z-M-Huang/vcp/main/standards/core-security.md", "severity": "critical", "tags": ["security", "owasp", "cwe"] },
    { "id": "core-new-standard", "url": "https://raw.githubusercontent.com/Z-M-Huang/vcp/main/standards/core-new-standard.md", "severity": "high", "tags": ["topic"] }
  ]
}

All standard URLs must be full HTTPS URLs — see schemas/vcp-scope-manifest.schema.json for the schema. The root standards/manifest.json (v2) maps scope names to scope manifest files (also full HTTPS URLs) and their applies conditions. You only need to edit the root manifest when adding a new scope.

applies Field (in root manifest)

Value	When Scope's Standards Are Loaded
"always"	Every project (core standards)
"web-frontend"	When scopes.web-frontend is true
"web-backend"	When scopes.web-backend is true
"database"	When scopes.database is true
"mobile"	When scopes.mobile is true
"desktop"	When scopes.desktop is true
"cli"	When scopes.cli is true
"devops"	When scopes.devops is true
"compliance:gdpr"	When "gdpr" is in compliance array
"compliance:pci-dss"	When "pci-dss" is in compliance array
"compliance:hipaa"	When "hipaa" is in compliance array