Service Manifest Reference
Status: Draft v0.1
Purpose
A service manifest is a YAML file that describes a single service in full, machine-readable detail. It is the document an agent reads when it needs to evaluate whether a service fits its requirements, what inputs are needed to order it, and what it can expect in return.
Service manifests are linked from the osp.md file and placed in an /osp/services/ directory by convention.
Schema Overview
A service manifest consists of six sections:
| Section | Purpose | Required |
|---|---|---|
| identity | Naming, classification, when to use / not use | Yes |
| evaluation | Parameters for agent comparison and selection | Yes |
| contract | Input requirements, output guarantees, engagement model | Recommended |
| delivery | Execution mode, timelines, status tracking | Recommended |
| governance | Access control, compliance, data handling | Recommended |
| lifecycle | Version, changelog, review cycle | Optional |
Not every service needs every section at full depth. A simple lookup service can omit governance entirely. A complex consulting engagement needs all sections. The schema is a maximum format — providers fill what applies.
Section 1: identity
Identifies the service and provides the semantic context an agent needs to decide whether this service is relevant.
osp_version: "0.1" # Required. Protocol version.
service:
identity:
id: "string" # Required. Unique identifier.
# Convention: domain.entity.action
# Example: "translog.transport.ltl"
name: "string" # Required. Human-readable name.
# Example: "LTL Transport Europe"
version: "string" # Required. Semver.
# Example: "2.1.0"
status: "string" # Required. One of:
# active, deprecated, draft, experimental
maturity: "string" # Recommended. Indicates how the service
# is currently delivered. One of:
# human, assisted, supervised, autonomous
# See Maturity Levels below.
summary: "string" # Required. 2-3 sentences describing what
# the service does.
when_to_use: "string" # Required. Conditions under which an
# agent should consider this service.
when_not_to_use: "string" # Required. Conditions under which this
# service is NOT appropriate.
tags: ["string"] # Recommended. Keywords for discovery.
domain: "string" # Optional. Business domain.
# Example: "logistics", "consulting"
service_family: "string" # Optional. Groups related services.
engagement_type: "string" # Recommended. One of:
# transactional | consultative | continuous
Maturity Levels
The maturity field indicates how the service is currently delivered. It does NOT affect the interface — agents interact identically regardless of maturity.
| Level | Meaning |
|---|---|
human | A human performs the service. The API is a facade. |
assisted | AI prepares, a human decides and delivers. |
supervised | AI delivers, a human reviews selectively. |
autonomous | Fully automated with monitoring. |
Section 2: evaluation
Contains the parameters an agent needs to compare this service against its requirements without placing an order.
evaluation:
capacity:
# Example for transport:
min_pallets: 5
max_pallets: 15
max_weight_kg: 12000
temperature_range: [2, 25]
# Example for consulting:
min_engagement_days: 10
max_parallel_engagements: 3
geography:
service_regions: ["string"] # ISO 3166-1 alpha-2 country codes
excluded_regions: ["string"]
performance:
standard_leadtime: "string" # Example: "48-96h"
express_available: true
express_leadtime: "string"
completion_rate: 0.97
on_time_rate: 0.94
average_quality_score: 4.6
sample_size: 4200
sample_period: "12 months"
pricing:
model: "string" # per_unit | per_hour | per_project |
# per_shipment | subscription | custom
currency: "string" # ISO 4217
indicative_range:
min: 0
max: 0
note: "string"
express_surcharge: "string"
token_pricing_available: true
certifications: ["string"]
sla:
response_time: "string"
tracking_available: true
incident_notification: "string"
late_delivery_compensation: "string"
quality_guarantee: "string"
confidence_note: "string"
Guidelines for the Evaluation Section
Be concrete. “Fast delivery” is useless for an agent. “48-96h standard, 24-36h express” is actionable.
Include ranges, not just averages. An agent that needs a guarantee cares about the worst case, not the average.
The confidence_note matters. It tells the agent how much to trust the numbers.
Section 3: contract
Defines what an agent needs to provide to order the service, what it will receive in return, and what guarantees apply.
contract:
engagement:
type: "string" # transactional | consultative | continuous
# For transactional:
quote_binding: true
quote_validity: "string"
# For consultative:
multi_phase: true
initial_phase_independent: true
scope_negotiation: "string"
# For continuous:
minimum_term: "string"
notice_period: "string"
individual_orders: true
input:
required_fields:
- name: "string"
type: "string" # string | number | boolean | date |
# datetime | enum | file | object | array
description: "string"
constraints: {}
optional_fields:
- name: "string"
type: "string"
description: "string"
default: "any"
constraints: {}
output:
fields:
- name: "string"
type: "string"
description: "string"
confidence_included: true
examples:
- scenario: "string"
input: {}
output: {}
preconditions:
- condition: "string"
on_failure: "string" # reject | skip | degrade
agent_instruction: "string"
postconditions:
- guarantee: "string"
Section 4: delivery
Describes how the service is executed and how the agent tracks progress.
delivery:
mode: "string" # synchronous | async_tracked | interactive
# For synchronous:
expected_duration: "string"
# For async_tracked:
tracking:
status_endpoint: true
webhook_support: true
update_frequency: "string"
# For interactive:
interaction:
input_requests_possible: true
review_points: true
max_interactions: 0
status_values:
- "accepted"
- "preparing"
- "in_progress"
- "review"
- "pending_input"
- "delivered"
- "completed"
- "disputed"
human_involvement:
disclosed: true
typical_touchpoints: 0
Section 5: governance
Describes access control, data handling, and compliance requirements.
governance:
access:
authentication_required: true
authorization_model: "string" # api_key | oauth2 | token_account
agent_registration_required: true
data:
input_sensitivity: "string" # public | internal | confidential | restricted
output_sensitivity: "string"
pii_fields: ["string"]
retention_period: "string"
deletion_on_request: true
compliance:
regulations: ["string"]
audit_trail: true
certifications: ["string"]
agent_restrictions:
rate_limit: "string"
budget_limit_enforceable: true
geographic_restrictions: ["string"]
Section 6: lifecycle
Version history and maintenance information.
lifecycle:
created: "date"
last_modified: "date"
changelog:
- version: "string"
date: "date"
changes: "string"
deprecation:
planned: false
successor: "string"
sunset_date: "date"
review:
next_review: "date"
review_cycle: "string"
Minimal Valid Manifest
The smallest valid service manifest contains only the required fields:
osp_version: "0.1"
service:
identity:
id: "example.service.basic"
name: "Basic Example Service"
version: "1.0.0"
status: "active"
summary: "A minimal service manifest demonstrating required fields only."
when_to_use: "Use this as a template when creating your first service manifest."
when_not_to_use: "Do not use in production. This is a documentation example."
evaluation:
geography:
service_regions: ["CH", "DE", "AT"]
performance:
standard_leadtime: "48h"
pricing:
model: "per_unit"
currency: "CHF"
indicative_range:
min: 100
max: 500
File Naming Convention
Service manifests are placed in /osp/services/ and named after the service:
/osp/services/ltl-transport.yaml
/osp/services/market-entry.yaml
/osp/services/managed-hosting.yaml
Use lowercase, hyphens for word separation, no spaces.
Token Efficiency Guidelines
- Keep
summary,when_to_use, andwhen_not_to_useunder 100 words each - Use concrete values instead of verbose descriptions
- Avoid repeating information across sections
- A full manifest should consume fewer than 1,500 tokens
- A minimal manifest should consume fewer than 400 tokens