YAML
Markup Hybrid since v1.0🗂️ Pulls top-level keys and named entries under well-known parents (jobs, services, volumes…). Anchor-aware.
.yml.yaml What gets detected
The public surface spec-sync tracks for YAML.
- Top-level mapping keys (any key at column 0)
- Named children of well-known parents: jobs, services, volumes, networks, secrets, stages, steps, targets, outputs, inputs, permissions, deployments
- YAML anchors (&anchor-name)
Detection rules
Top-level mapping keys
Any key at column 0 (no leading whitespace) followed by a colon is a top-level symbol. Pattern: ^(key): with no indentation.
name: CI
on: push
jobs:
# ...
services:
# ...Named children of well-known parents
For a fixed set of well-known structural parents (jobs, services, volumes, networks, secrets, stages, steps, targets, outputs, inputs, permissions, deployments), immediate children are extracted as parent.child symbols.
jobs:
test:
runs-on: ubuntu-latest
lint:
runs-on: ubuntu-latest
# Extracted: jobs.test, jobs.lint
services:
web:
image: nginx
db:
image: postgres
# Extracted: services.web, services.dbYAML anchors
YAML anchor definitions (&anchor-name) are extracted as named symbols. Aliases (*alias) are not separately captured.
defaults: &defaults
timeout: 30
retries: 3
# Extracted anchor: defaultsMulti-document YAML
Files with --- separators (Kubernetes manifests, etc.) are handled correctly. Top-level keys from all documents are extracted.
apiVersion: apps/v1
kind: Deployment
---
apiVersion: v1
kind: Service
# Extracts: apiVersion, kind from both documentsExample: spec & source
The *.spec.md contract on the left,
the YAML source it documents on the right. spec-sync matches the two.
Spec (*.spec.md)
---
module: ci-workflow
version: 1
status: stable
files:
- .github/workflows/ci.yml
---
## Purpose
CI/CD workflow configuration.
## Public API
| Symbol | Kind | Description |
|--------|------|-------------|
| `jobs` | mapping | CI job definitions |
| `jobs.test` | job | Run test suite |
| `jobs.lint` | job | Run linters |
| `jobs.build` | job | Build artifacts |
## Change Log
| Date | Change |
|------|--------|
| 2026-01-01 | Initial |Source
name: CI
on:
push:
branches: [main]
pull_request:
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: cargo test
lint:
runs-on: ubuntu-latest
steps:
- run: cargo clippy
build:
runs-on: ubuntu-latest
steps:
- run: cargo build --releaseCaveats
- Regex-based parsing; does not interpret full YAML semantics (merge keys, complex scalars, etc.).
- Multi-document YAML (---) is supported for top-level keys but nested children are only extracted from the first occurrence of a well-known parent.
- Flow-style YAML ({key: value}) is not parsed for top-level keys.
- Only the fixed list of well-known parent keys produces dotted child symbols; arbitrary nested keys are not extracted.