mdm-ordinis/docs/user-guide/bundle-authoring.md

Authoring a Bundle

How to package справочники как distributable Ordinis bundle.

См. также: Bundle Format Specification — formal spec.

---

Quick start

# 1. Create bundle structure
mkdir -p my-bundle/src/main/resources/bundles/my-id
cd my-bundle

# 2. Add at least one schema
cat > src/main/resources/bundles/my-id/widget.schema.json <<'JSON'
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "x-id-source": "code",
  "required": ["code", "name"],
  "additionalProperties": false,
  "properties": {
    "code": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{1,31}$", "x-unique": true },
    "name": {
      "type": "object", "x-localized": true,
      "patternProperties": { "^[a-z]{2}-[A-Z]{2}$": { "type": "string" } },
      "required": ["ru-RU"]
    }
  }
}
JSON

# 3. Write manifest
cat > manifest.yaml <<'YAML'
apiVersion: ordinis.io/v1
kind: Bundle
metadata:
  id: my-org.widgets
  name: My Widgets Bundle
  version: 1.0.0
  scope: PUBLIC
dictionaries:
  - name: widget
    schemaVersion: 1.0.0
    scope: PUBLIC
    schemaRef: src/main/resources/bundles/my-id/widget.schema.json
YAML

---

Versioning

• metadata.version — semver. Patch на data fixes, minor на add'инге dict'ов, major на breaking schema changes.
• dictionaries[].schemaVersion — per-dict semver, independent от bundle version. Bump когда меняется shape конкретной schema.
• Breaking schema change (remove required field, change type, add additionalProperties: false) → MAJOR bump bundle.

---

Validation locally

# Через maven (если bundle — Maven artifact):
mvn test -pl ordinis-bundle-spec -Dtest=CuodManifestFixtureTest

# Или programmatically:
import cloud.nstart.terravault.ordinis.bundle.spec.*;

byte[] yaml = Files.readAllBytes(Path.of("manifest.yaml"));
List<String> errors = ManifestParser.parseAndValidate(yaml);
if (!errors.isEmpty()) {
  errors.forEach(System.err::println);
  System.exit(1);
}

---

Signing (production publish)

Ed25519 keypair generation:

openssl genpkey -algorithm Ed25519 -out signing-priv.pem
openssl pkey -in signing-priv.pem -pubout -outform DER -out signing-pub.der

Sign bundle archive (until publisher Maven plugin lands — manual для now):

byte[] archive = Files.readAllBytes(Path.of("bundle.tar.gz"));
byte[] privKey = Files.readAllBytes(Path.of("signing-priv.der")); // convert PEM→DER first
String sig = BundleSignatureVerifier.sign(archive, privKey);
// → patch manifest.yaml: metadata.signature: <sig>
//   OR write sidecar bundle.sig: <sig>

Public key распространяется к operators которые verify bundles перед install.

---

Conventions

Naming

• metadata.id — reverse-DNS (ru.cuod.dzz-ground-segment, com.acme.widgets).
• dictionaries[].name — snake_case (spacecraft, ground_station, frequency_band).

Locales

Localized fields (x-localized: true) — каждое значение это объект {lang-COUNTRY: "..."}:

"name": { "ru-RU": "Космический аппарат", "en-US": "Spacecraft" }

Bundle сам не объявляет supported locales — это per-dict. Manifest may add optional metadata.locales в future v1.x но spec строго ignores unknown сейчас.

Foreign keys

x-references: "<target_dict>.<field>" — backend validates на write. Если target dict в том же bundle — order ensured (см. consumer protocol §6 в spec).

---

Anti-patterns

• ❌ Не shipпите additionalProperties: true в production schemas — типизация теряется
• ❌ Не используйте $ref к внешним URLs (security risk + offline build fail)
• ❌ Не делайте 100+ dicts в одном bundle — расщепляйте по domain (e.g. cuod-spacecraft, cuod-radio)
• ❌ Не bump'айте schemaVersion без реального schema change

---

Handoff checklist (Java team)

Когда передаёте bundle authoring к новой команде:

1. ✅ Прочитать bundle-format-spec.md
2. ✅ Изучить ordinis-cuod-bundle/manifest.yaml как working example
3. ✅ Прогнать mvn test -pl ordinis-bundle-spec локально
4. ✅ Generate signing keypair, distribute pub key к ops
5. ✅ Set up CI publish job (когда ordinis-bundle-publisher plugin landed)

Для вопросов: ordinis maintainers (см. CODEOWNERS).