This document provides guidance for AI tools working with Domain Connect templates in this repository.
These rules apply when adding or modifying templates in this repository.
The template file schema is defined in template.schema. This schema MUST be followed for all template files.
Key schema requirements:
- Templates must include required fields:
providerId,providerName,serviceId,serviceName,records - Record types supported: A, AAAA, CNAME, NS, TXT, MX, SPFM, SRV, REDIR301, REDIR302, APEXCNAME, and ANY
- Templates must follow the JSON Schema defined in
template.schema
Before submitting changes, you MUST validate every added or modified template with the official linter.
PRs whose templates pass the Automerge Check workflow (dc-template-linter -merge-or-fail) receive the automerge-possible label and are approved and merged much faster. PRs that fail it are queued for manual review by a maintainer, which takes considerably longer. Always aim for a clean -merge-or-fail run; only deviate when a documented exception applies, and then justify it in the PR description.
Requires Go 1.22 or newer:
go install github.com/Domain-Connect/dc-template-linter@latestThe binary lands in $(go env GOPATH)/bin; ensure it is on PATH.
Run these checks on each changed template file and inspect the exit code (echo $?):
-
Fast-track check (identical to the Automerge Check workflow):
dc-template-linter -merge-or-fail <template-file.json>
Exit code
0means the PR qualifies for fast-track approval. A non-zero exit code means it will go to manual review — fix the reportedDCTLxxxxissues (see the linter wiki) and re-run. -
Full check (identical to the Lint Domain Connect Templates workflow):
dc-template-linter -tolerate warn <template-file.json>
Must exit
0, otherwise the workflow fails and the PR cannot be merged. -
Version bump (modified templates only): the
versionfield must be incremented; the workflow fails if a changed template has noversionchange. -
Logo reachability (not run in CI, but required by the PR template checkbox; requires network):
dc-template-linter -logos <template-file.json>
All templates must pass the full check and, if modified, carry a version bump before being considered valid.
Note: If
dc-template-linterreturns a non-zero exit value, the template is invalid (full check) or not eligible for fast track (-merge-or-fail) and should be corrected before submission. Never report a check as passed without actually running it and seeing exit code0.
Template files must be named following this pattern:
providerId.serviceId.json
Example: myprovider.com.website.json
Place template files in the root directory of the repository.
For reference, example templates using the provider exampleservice.domainconnect.org are available in this repository. These templates demonstrate proper structure and can be used as a starting point when creating new templates.
When committing template changes, use the following format for the subject line:
- New template:
add <providerName>, <serviceName>(e.g.,add Example Domain Connect Service, Stateless Hosting Primary) - Modified template:
modify <providerName>, <serviceName> - Deleted template:
delete <providerName>, <serviceName> - Multiple templates:
<providerName>, <num> templates(e.g.,Example Domain Connect Service, 3 templates)
The commit body should follow the structure defined in .github/pull_request_template.md. When creating commit messages, AI tools may:
- Assist with checking
[ ]checkboxes from the PR template - Help verify template quality rules
IMPORTANT: AI tools MUST NEVER fabricate or hallucinate "Online Editor test results" links. These must be generated by actually using the Online Editor.
When modifying or creating templates, ensure compliance with these critical rules:
- Always set
syncPubKeyDomain- Enables cryptographic verification (preferred overwarnPhishing) - Never set
syncPubKeyDomainandwarnPhishingtogether - They are mutually exclusive - Set
syncRedirectDomainwhen usingredirect_uriin synchronous flow - Never use TXT records for SPF - Use the
SPFMrecord type instead - Set
txtConflictMatchingModeon TXT records that must be unique (e.g., DMARC, verification tokens) - Scope variables narrowly - Avoid bare variables as full record values; use fixed prefixes
- Scope host variables narrowly - Fix non-variable parts in host fields
- Never use variables in
hostto target subdomains - Use the standardhostparameter instead - Never write
%host%explicitly in thehostattribute - The protocol handles this automatically - Set
essentialon records users may need to change independently
For complete details, see the README.md.