Skip to content

Add support for requesting OpenAPI schemas #193

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
negz merged 3 commits into from
Feb 6, 2026
+718 −127
Merged

Add support for requesting OpenAPI schemas #193

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
21d3696
Add support for requesting OpenAPI schemas
negz Jan 15, 2026
d726cca
Add support for capability detection
negz Feb 5, 2026
f91254e
Add advertises_capabilities and has_capability helpers
negz Feb 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 68 additions & 2 deletions crossplane/function/proto/v1/run_function.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -90,6 +90,13 @@ message RunFunctionRequest {
// satisfy the request. This field is only populated when the function uses
// resources in its requirements.
map<string, Resources> required_resources = 8;

// Optional schemas that the function specified in its requirements. The map
// key corresponds to the key in a RunFunctionResponse's requirements.schemas
// field. If a function requested a schema that could not be found, Crossplane
// sets the map key to an empty Schema message to indicate that it attempted
// to satisfy the request.
map<string, Schema> required_schemas = 9;
}

// Credentials that a function may use to communicate with an external system.
Expand Down Expand Up @@ -156,6 +163,44 @@ message RequestMeta {
// An opaque string identifying a request. Requests with identical tags will
// be otherwise identical.
string tag = 1;

// Capabilities supported by this version of Crossplane. Functions may use
// this to determine whether Crossplane will honor certain fields in their
// response, or populate certain fields in their request.
repeated Capability capabilities = 2;
}

// Capability indicates that Crossplane supports a particular feature.
// Functions can check for capabilities to determine whether Crossplane will
// honor a particular request or response field.
enum Capability {
CAPABILITY_UNSPECIFIED = 0;

// Crossplane sends capabilities in RequestMeta. If this capability is
// present, the function knows that if another capability is absent, it's
// because Crossplane doesn't support it (not because Crossplane predates
// capability advertisement). Added in Crossplane v2.2.
CAPABILITY_CAPABILITIES = 1;

// Crossplane supports the requirements.resources field. Functions can return
// resource requirements and Crossplane will fetch the requested resources and
// return them in required_resources. Added in Crossplane v1.15.
CAPABILITY_REQUIRED_RESOURCES = 2;

// Crossplane supports the credentials field. Functions can receive
// credentials from secrets specified in the Composition. Added in Crossplane
// v1.16.
CAPABILITY_CREDENTIALS = 3;

// Crossplane supports the conditions field. Functions can return status
// conditions to be applied to the XR and optionally its claim. Added in
// Crossplane v1.17.
CAPABILITY_CONDITIONS = 4;

// Crossplane supports the requirements.schemas field. Functions can request
// OpenAPI schemas and Crossplane will return them in required_schemas. Added
// in Crossplane v2.2.
CAPABILITY_REQUIRED_SCHEMAS = 5;
}

// Requirements that must be satisfied for a function to run successfully.
Expand All @@ -169,6 +214,27 @@ message Requirements {
// Resources that this function requires. The map key uniquely identifies the
// group of resources.
map<string, ResourceSelector> resources = 2;

// Schemas that this function requires. The map key uniquely identifies the
// schema request.
map<string, SchemaSelector> schemas = 3;
}

// SchemaSelector identifies a resource kind whose OpenAPI schema is requested.
message SchemaSelector {
// API version of the resource kind, e.g. "example.org/v1".
string api_version = 1;

// Kind of resource, e.g. "MyResource".
string kind = 2;
}

// Schema represents the OpenAPI schema for a resource kind.
message Schema {
// The OpenAPI v3 schema of the resource kind as unstructured JSON.
// For CRDs this is the spec.versions[].schema.openAPIV3Schema field.
// Empty if Crossplane could not find a schema for the requested kind.
optional google.protobuf.Struct openapi_v3 = 1;
}

// ResourceSelector selects a group of resources, either by name or by label.
Expand Down Expand Up @@ -267,7 +333,7 @@ message Resource {
// * A function should set this field to READY_TRUE in a RunFunctionResponse
// to indicate that a desired XR is ready. This overwrites the standard
// readiness detection that determines the ready state of the composite by the
// ready state of the the composed resources.
// ready state of the composed resources.
//
// Ready is only used for composition. It's ignored by Operations.
Ready ready = 3;
Expand Down Expand Up @@ -367,4 +433,4 @@ enum Status {
STATUS_CONDITION_TRUE = 2;

STATUS_CONDITION_FALSE = 3;
}
}
126 changes: 70 additions & 56 deletions crossplane/function/proto/v1/run_function_pb2.py
View file
Open in desktop

Large diffs are not rendered by default.

61 changes: 55 additions & 6 deletions crossplane/function/proto/v1/run_function_pb2.pyi
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,15 @@ from typing import ClassVar as _ClassVar, Optional as _Optional, Union as _Union

DESCRIPTOR: _descriptor.FileDescriptor

class Capability(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
__slots__ = ()
CAPABILITY_UNSPECIFIED: _ClassVar[Capability]
CAPABILITY_CAPABILITIES: _ClassVar[Capability]
CAPABILITY_REQUIRED_RESOURCES: _ClassVar[Capability]
CAPABILITY_CREDENTIALS: _ClassVar[Capability]
CAPABILITY_CONDITIONS: _ClassVar[Capability]
CAPABILITY_REQUIRED_SCHEMAS: _ClassVar[Capability]

class Ready(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
__slots__ = ()
READY_UNSPECIFIED: _ClassVar[Ready]
Expand All @@ -36,6 +45,12 @@ class Status(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
STATUS_CONDITION_UNKNOWN: _ClassVar[Status]
STATUS_CONDITION_TRUE: _ClassVar[Status]
STATUS_CONDITION_FALSE: _ClassVar[Status]
CAPABILITY_UNSPECIFIED: Capability
CAPABILITY_CAPABILITIES: Capability
CAPABILITY_REQUIRED_RESOURCES: Capability
CAPABILITY_CREDENTIALS: Capability
CAPABILITY_CONDITIONS: Capability
CAPABILITY_REQUIRED_SCHEMAS: Capability
READY_UNSPECIFIED: Ready
READY_TRUE: Ready
READY_FALSE: Ready
Expand All @@ -52,7 +67,7 @@ STATUS_CONDITION_TRUE: Status
STATUS_CONDITION_FALSE: Status

class RunFunctionRequest(_message.Message):
__slots__ = ("meta", "observed", "desired", "input", "context", "extra_resources", "credentials", "required_resources")
__slots__ = ("meta", "observed", "desired", "input", "context", "extra_resources", "credentials", "required_resources", "required_schemas")
class ExtraResourcesEntry(_message.Message):
__slots__ = ("key", "value")
KEY_FIELD_NUMBER: _ClassVar[int]
Expand All @@ -74,6 +89,13 @@ class RunFunctionRequest(_message.Message):
key: str
value: Resources
def __init__(self, key: _Optional[str] = ..., value: _Optional[_Union[Resources, _Mapping]] = ...) -> None: ...
class RequiredSchemasEntry(_message.Message):
__slots__ = ("key", "value")
KEY_FIELD_NUMBER: _ClassVar[int]
VALUE_FIELD_NUMBER: _ClassVar[int]
key: str
value: Schema
def __init__(self, key: _Optional[str] = ..., value: _Optional[_Union[Schema, _Mapping]] = ...) -> None: ...
META_FIELD_NUMBER: _ClassVar[int]
OBSERVED_FIELD_NUMBER: _ClassVar[int]
DESIRED_FIELD_NUMBER: _ClassVar[int]
Expand All @@ -82,6 +104,7 @@ class RunFunctionRequest(_message.Message):
EXTRA_RESOURCES_FIELD_NUMBER: _ClassVar[int]
CREDENTIALS_FIELD_NUMBER: _ClassVar[int]
REQUIRED_RESOURCES_FIELD_NUMBER: _ClassVar[int]
REQUIRED_SCHEMAS_FIELD_NUMBER: _ClassVar[int]
meta: RequestMeta
observed: State
desired: State
Expand All @@ -90,7 +113,8 @@ class RunFunctionRequest(_message.Message):
extra_resources: _containers.MessageMap[str, Resources]
credentials: _containers.MessageMap[str, Credentials]
required_resources: _containers.MessageMap[str, Resources]
def __init__(self, meta: _Optional[_Union[RequestMeta, _Mapping]] = ..., observed: _Optional[_Union[State, _Mapping]] = ..., desired: _Optional[_Union[State, _Mapping]] = ..., input: _Optional[_Union[_struct_pb2.Struct, _Mapping]] = ..., context: _Optional[_Union[_struct_pb2.Struct, _Mapping]] = ..., extra_resources: _Optional[_Mapping[str, Resources]] = ..., credentials: _Optional[_Mapping[str, Credentials]] = ..., required_resources: _Optional[_Mapping[str, Resources]] = ...) -> None: ...
required_schemas: _containers.MessageMap[str, Schema]
def __init__(self, meta: _Optional[_Union[RequestMeta, _Mapping]] = ..., observed: _Optional[_Union[State, _Mapping]] = ..., desired: _Optional[_Union[State, _Mapping]] = ..., input: _Optional[_Union[_struct_pb2.Struct, _Mapping]] = ..., context: _Optional[_Union[_struct_pb2.Struct, _Mapping]] = ..., extra_resources: _Optional[_Mapping[str, Resources]] = ..., credentials: _Optional[_Mapping[str, Credentials]] = ..., required_resources: _Optional[_Mapping[str, Resources]] = ..., required_schemas: _Optional[_Mapping[str, Schema]] = ...) -> None: ...

class Credentials(_message.Message):
__slots__ = ("credential_data",)
Expand Down Expand Up @@ -136,13 +160,15 @@ class RunFunctionResponse(_message.Message):
def __init__(self, meta: _Optional[_Union[ResponseMeta, _Mapping]] = ..., desired: _Optional[_Union[State, _Mapping]] = ..., results: _Optional[_Iterable[_Union[Result, _Mapping]]] = ..., context: _Optional[_Union[_struct_pb2.Struct, _Mapping]] = ..., requirements: _Optional[_Union[Requirements, _Mapping]] = ..., conditions: _Optional[_Iterable[_Union[Condition, _Mapping]]] = ..., output: _Optional[_Union[_struct_pb2.Struct, _Mapping]] = ...) -> None: ...

class RequestMeta(_message.Message):
__slots__ = ("tag",)
__slots__ = ("tag", "capabilities")
TAG_FIELD_NUMBER: _ClassVar[int]
CAPABILITIES_FIELD_NUMBER: _ClassVar[int]
tag: str
def __init__(self, tag: _Optional[str] = ...) -> None: ...
capabilities: _containers.RepeatedScalarFieldContainer[Capability]
def __init__(self, tag: _Optional[str] = ..., capabilities: _Optional[_Iterable[_Union[Capability, str]]] = ...) -> None: ...

class Requirements(_message.Message):
__slots__ = ("extra_resources", "resources")
__slots__ = ("extra_resources", "resources", "schemas")
class ExtraResourcesEntry(_message.Message):
__slots__ = ("key", "value")
KEY_FIELD_NUMBER: _ClassVar[int]
Expand All @@ -157,11 +183,34 @@ class Requirements(_message.Message):
key: str
value: ResourceSelector
def __init__(self, key: _Optional[str] = ..., value: _Optional[_Union[ResourceSelector, _Mapping]] = ...) -> None: ...
class SchemasEntry(_message.Message):
__slots__ = ("key", "value")
KEY_FIELD_NUMBER: _ClassVar[int]
VALUE_FIELD_NUMBER: _ClassVar[int]
key: str
value: SchemaSelector
def __init__(self, key: _Optional[str] = ..., value: _Optional[_Union[SchemaSelector, _Mapping]] = ...) -> None: ...
EXTRA_RESOURCES_FIELD_NUMBER: _ClassVar[int]
RESOURCES_FIELD_NUMBER: _ClassVar[int]
SCHEMAS_FIELD_NUMBER: _ClassVar[int]
extra_resources: _containers.MessageMap[str, ResourceSelector]
resources: _containers.MessageMap[str, ResourceSelector]
def __init__(self, extra_resources: _Optional[_Mapping[str, ResourceSelector]] = ..., resources: _Optional[_Mapping[str, ResourceSelector]] = ...) -> None: ...
schemas: _containers.MessageMap[str, SchemaSelector]
def __init__(self, extra_resources: _Optional[_Mapping[str, ResourceSelector]] = ..., resources: _Optional[_Mapping[str, ResourceSelector]] = ..., schemas: _Optional[_Mapping[str, SchemaSelector]] = ...) -> None: ...

class SchemaSelector(_message.Message):
__slots__ = ("api_version", "kind")
API_VERSION_FIELD_NUMBER: _ClassVar[int]
KIND_FIELD_NUMBER: _ClassVar[int]
api_version: str
kind: str
def __init__(self, api_version: _Optional[str] = ..., kind: _Optional[str] = ...) -> None: ...

class Schema(_message.Message):
__slots__ = ("openapi_v3",)
OPENAPI_V3_FIELD_NUMBER: _ClassVar[int]
openapi_v3: _struct_pb2.Struct
def __init__(self, openapi_v3: _Optional[_Union[_struct_pb2.Struct, _Mapping]] = ...) -> None: ...

class ResourceSelector(_message.Message):
__slots__ = ("api_version", "kind", "match_name", "match_labels", "namespace")
Expand Down
68 changes: 67 additions & 1 deletion crossplane/function/proto/v1beta1/run_function.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -92,6 +92,13 @@ message RunFunctionRequest {
// satisfy the request. This field is only populated when the function uses
// resources in its requirements.
map<string, Resources> required_resources = 8;

// Optional schemas that the function specified in its requirements. The map
// key corresponds to the key in a RunFunctionResponse's requirements.schemas
// field. If a function requested a schema that could not be found, Crossplane
// sets the map key to an empty Schema message to indicate that it attempted
// to satisfy the request.
map<string, Schema> required_schemas = 9;
}

// Credentials that a function may use to communicate with an external system.
Expand Down Expand Up @@ -158,6 +165,44 @@ message RequestMeta {
// An opaque string identifying a request. Requests with identical tags will
// be otherwise identical.
string tag = 1;

// Capabilities supported by this version of Crossplane. Functions may use
// this to determine whether Crossplane will honor certain fields in their
// response, or populate certain fields in their request.
repeated Capability capabilities = 2;
}

// Capability indicates that Crossplane supports a particular feature.
// Functions can check for capabilities to determine whether Crossplane will
// honor a particular request or response field.
enum Capability {
CAPABILITY_UNSPECIFIED = 0;

// Crossplane sends capabilities in RequestMeta. If this capability is
// present, the function knows that if another capability is absent, it's
// because Crossplane doesn't support it (not because Crossplane predates
// capability advertisement). Added in Crossplane v2.2.
CAPABILITY_CAPABILITIES = 1;

// Crossplane supports the requirements.resources field. Functions can return
// resource requirements and Crossplane will fetch the requested resources and
// return them in required_resources. Added in Crossplane v1.15.
CAPABILITY_REQUIRED_RESOURCES = 2;

// Crossplane supports the credentials field. Functions can receive
// credentials from secrets specified in the Composition. Added in Crossplane
// v1.16.
CAPABILITY_CREDENTIALS = 3;

// Crossplane supports the conditions field. Functions can return status
// conditions to be applied to the XR and optionally its claim. Added in
// Crossplane v1.17.
CAPABILITY_CONDITIONS = 4;

// Crossplane supports the requirements.schemas field. Functions can request
// OpenAPI schemas and Crossplane will return them in required_schemas. Added
// in Crossplane v2.2.
CAPABILITY_REQUIRED_SCHEMAS = 5;
}

// Requirements that must be satisfied for a function to run successfully.
Expand All @@ -171,6 +216,27 @@ message Requirements {
// Resources that this function requires. The map key uniquely identifies the
// group of resources.
map<string, ResourceSelector> resources = 2;

// Schemas that this function requires. The map key uniquely identifies the
// schema request.
map<string, SchemaSelector> schemas = 3;
}

// SchemaSelector identifies a resource kind whose OpenAPI schema is requested.
message SchemaSelector {
// API version of the resource kind, e.g. "example.org/v1".
string api_version = 1;

// Kind of resource, e.g. "MyResource".
string kind = 2;
}

// Schema represents the OpenAPI schema for a resource kind.
message Schema {
// The OpenAPI v3 schema of the resource kind as unstructured JSON.
// For CRDs this is the spec.versions[].schema.openAPIV3Schema field.
// Empty if Crossplane could not find a schema for the requested kind.
optional google.protobuf.Struct openapi_v3 = 1;
}

// ResourceSelector selects a group of resources, either by name or by label.
Expand Down Expand Up @@ -269,7 +335,7 @@ message Resource {
// * A function should set this field to READY_TRUE in a RunFunctionResponse
// to indicate that a desired XR is ready. This overwrites the standard
// readiness detection that determines the ready state of the composite by the
// ready state of the the composed resources.
// ready state of the composed resources.
//
// Ready is only used for composition. It's ignored by Operations.
Ready ready = 3;
Expand Down
Loading