Submissions Guide

The SDK provides two high-level classes for submitting declarations to NetOrca from a repository — one for consumers and one for service owners. Both are designed to run inside CI/CD pipelines.

---

Consumer Submission

Validates and submits application declarations from a consumer repository.

Repository structure

your-repo/
└── .netorca/
    ├── config.yaml       # Connection settings
    ├── app1.yaml         # Application declaration
    └── app2.yaml         # Application declaration

config.yaml

netorca_global:
  base_url: https://your-instance.netorca.io/v1
  metadata:
    team_name: my-team      # Optional — resolved from API key if omitted
    team_email: team@example.com

Application declaration — the top-level key is the application name (not the filename):

my-application:
  metadata:
    owner: platform-team
  services:
    DATABASE:
      engine: postgres
      size: medium

Basic usage

from netorca_sdk import NetOrcaClient, ConsumerSubmission

client = NetOrcaClient(
    fqdn="https://your-instance.netorca.io/v1",
    api_key="YOUR_API_KEY",
    context="consumer",
)

submission = ConsumerSubmission(client, repository_path="./")

ok, errors = submission.validate(pretty_print=True)
if ok:
    ok, errors = submission.submit(pretty_print=True)

Methods

validate(pretty_print=False)

Validates declarations without submitting. Returns (True, {}) on success or (False, {app: errors}) on failure.

ok, errors = submission.validate()
ok, errors = submission.validate(pretty_print=True)      # print table to console

submit(pretty_print=False, commit_id=None)

Submits declarations. Attaches the current git commit SHA automatically.

ok, errors = submission.submit()
ok, errors = submission.submit(commit_id="abc123")       # override commit SHA
ok, errors = submission.submit(commit_id="")             # skip commit SHA

JUnit XML

Generate a JUnit report for CI systems that collect test results:

from netorca_sdk.junit_reporter import JUnitReporter

ok, errors = submission.validate()
if not ok:
    reporter = JUnitReporter(output_path="junit.xml")
    reporter.write(errors)

CI/CD pipeline script

# netorca_runner.py
import os, sys
from netorca_sdk import NetOrcaClient, ConsumerSubmission
from netorca_sdk.utils import RepositoryLoader
from netorca_sdk.exceptions import NetorcaBaseException

try:
    data = RepositoryLoader.load_consumer_repository("./")
    client = NetOrcaClient(
        fqdn=data["config"]["netorca_global"]["base_url"],
        api_key=os.environ["NETORCA_API_KEY"],
        context="consumer",
    )
    submission = ConsumerSubmission(client)
    validate_only = os.environ.get("NETORCA_VALIDATE_ONLY", "True") == "True"
    ok, _ = submission.validate(pretty_print=True) if validate_only else submission.submit(pretty_print=True)
    sys.exit(0 if ok else 1)
except NetorcaBaseException as e:
    print(f"Error: {e}")
    sys.exit(1)

GitLab CI:

netorca:
  image: python:3.11
  script:
    - pip install netorca-sdk
    - python netorca_runner.py
  variables:
    NETORCA_API_KEY: $NETORCA_API_KEY
    NETORCA_VALIDATE_ONLY: "False"

ConsumerSubmission parameters

Parameter	Type	Default	Description
client	NetOrcaClient	required	Client with context="consumer"
repository_path	str	"./"	Path to the repository root
netorca_directory	str	".netorca"	Name of the declarations directory

---

Service Owner Submission

Publishes service definitions and uploads AI processors and context documents from a service owner repository.

Repository structure

your-repo/
└── .netorca/
    ├── config.json              # Connection settings
    └── my-service/              # One folder per service
        ├── my-service.json      # Service definition
        ├── my-service.md        # Optional: service README
        ├── pack/                # Optional: AI processor prompts
        │   ├── config.txt
        │   ├── verify.txt
        │   ├── execute.txt
        │   └── validate.txt
        └── context/             # Optional: AI context documents
            └── overview.md

config.json

{
  "netorca_global": {
    "base_url": "https://your-instance.netorca.io/v1"
  }
}

Basic usage

from netorca_sdk import NetOrcaClient, ServiceOwnerSubmission

client = NetOrcaClient(
    fqdn="https://your-instance.netorca.io/v1",
    api_key="YOUR_API_KEY",
    context="serviceowner",
)

submission = ServiceOwnerSubmission(client, repository_path="./")

is_valid, errors = submission.validate()
if is_valid:
    results = submission.submit()
    for service_name, result in results.items():
        print(f"{service_name}: {result['status']}")

Methods

validate()

Validates all service definitions. Returns (True, {}) or (False, {service_name: errors}).

submit(upload_pack=True, upload_context=True, skip_duplicate_documents=True)

Publishes services and uploads associated files.

results = submission.submit()

# Control what gets uploaded
results = submission.submit(
    upload_pack=True,
    upload_context=True,
    skip_duplicate_documents=False   # re-upload existing context docs
)

Pack prompts

Files in pack/ are uploaded as AI processors. Both .txt and .md are supported.

Filename	Action type
config.[txt/md]	config
verify.[txt/md]	verify
execute.[txt/md]	execution
validate.[txt/md]	change_instance_validator
optimizer.[txt/md]	optimiser

An optional {type}.json sets the response schema. An optional {type}-ui.json sets the generative UI schema.

ServiceOwnerSubmission parameters

Parameter	Type	Default	Description
client	NetOrcaClient	required	Client with context="serviceowner"
repository_path	str	required	Path to the repository root
netorca_directory	str	".netorca"	Name of the service definitions directory