Method Definitions

CK language 2 lets a type or an interface declare methods: named, versioned operations with typed parameters, a result, declared error codes, authorization and execution settings. Methods are the planned way to change attributes that must not be written generically (access: MethodOnly) and to replace ad-hoc REST endpoints.

Definitions only

In this phase methods are definitions only. They are validated by the compiler, persisted, shown in the generated documentation and turned into generated C# contracts — but there is no invocation yet: no GraphQL method mutations, no handler dispatch. The method runtime follows in a later phase. Defining methods now lets models settle their contracts early.

Syntax

types:
  - typeId: Device
    # ...
    methods:
      - methodId: UpdateFirmware-1
        kind: Instance                 # Instance (default) | Static
        description: Installs a firmware version.
        parameters:
          - name: version
            valueType: String
          - name: signingKey
            valueType: String
            sensitive: true            # never logged, never in audit or traces
        errors:
          - code: FIRMWARE_REJECTED
            description: The device refused the image.
        authorization:
          roles: [ AssetManagement ]   # any of these roles
        execution:
          timeoutSeconds: 60           # 1..300, default 15
          idempotent: false            # default false

Key	Required	Description
methodId	yes	PascalCase name with element version, e.g. ChangePassword-1. A changed signature is published as a new version (ChangePassword-2).
kind	no	Instance (default, called on one entity) or Static.
description	no	Free text.
parameters	no	List of name (camelCase), valueType, valueCkRecordId / valueCkEnumId (for Record / Enum), isOptional, sensitive, description.
result	no	valueType plus valueCkRecordId / valueCkEnumId. Omit for methods without a result.
errors	no	Declared business error codes: code (UPPER_SNAKE_CASE, no METHOD_ prefix — reserved for platform errors), description.
authorization	no	roles (any of; names compare case-insensitively), allowSelf (the caller's user id equals the target entity's id; instance methods only), scopes (additional scopes, all required; octo_api is always required). Default-deny: a method without authorization, or with empty roles, can only be invoked by administrators (not by the owner). Role and scope names use letters, digits and _ - . : /, starting with a letter or digit (message 104).
execution	no	timeoutSeconds (1–300, default 15), idempotent (default false).
visibility	no	Public (default) or Internal.

Parameter and result value types: String, Boolean, DateTime, DateTimeOffset, TimeSpan, Int, Int64, Double, StringArray, IntArray, Enum, Record.

Methods on interfaces use the same schema. Methods are inherited by derived types and by types implementing the interface.

Compiler Rules

Rule	Message
A method id is unique on a type, and a type does not redeclare an inherited method id (no overrides)	100
Parameters reference known records/enums, names are unique, Record/Enum have exactly the matching valueCkRecordId/valueCkEnumId	101
The names Create, Update, Delete are reserved (case-insensitive)	102
Error codes are unique and do not start with METHOD_	103
allowSelf: true is not allowed on a Static method	104
A type redeclares an interface method with a different invocation contract (kind, parameters, result, error codes)	122
Two methods of a model produce the same generated C# name (User + ChangePassword vs. UserChange + Password)	125

Generated Code

For each type method the source generator emits:

• a method id constant in the model's *CkIds class, e.g. DeviceUpdateFirmwareMethodId = "Acme.Assets/Device.UpdateFirmware-1" (a version above 1 is appended: DeviceUpdateFirmware2MethodId);
• a parameter record DeviceUpdateFirmwareParameters (required parameters are required, optional ones nullable; sensitive parameters print as *** in ToString());
• a result record {Type}{Method}Result { Value } when the method has a result.

Interface methods get no records.

Versioning

• A new method is a Minor change.
• Removing a method, or changing its signature (kind, parameters, result, errors, authorization, execution), is Major — publish a new method version (UpdateFirmware-2) instead.
• description and parameter/error descriptions are Patch changes; they are not part of the signature.

See Also

• Access modifiers — access: MethodOnly
• Interfaces
• Compiler messages