Wreken Specification

Version 2.0.2

Status: Stable (HTTP + SDK Unified)
Audience: API teams, SDK authors, AI systems (LLMs), tooling platforms
Goal: Fully define how APIs and SDKs are called, constructed, and executed — without inference.

Table of Contents

1. Purpose
2. Core Design Principles
3. Top-Level Structure
4. CLIENTS (SDK Construction)
5. METHODS (Unified HTTP + SDK)
6. EXECUTION
7. HTTP Section
8. INPUTS
9. RETURNS
10. ERRORS
11. STRUCTS
12. Pagination (Optional)
13. SOURCES
14. DEFAULTS
15. Void / Empty Returns
16. Relationship to Mini-Wrekenfiles
17. AI & Code Generation Rules (Normative)
18. License

---

1. Purpose

A Wrekenfile is an execution-first spec file that describes callable intent.

It unifies:

• HTTP APIs (transport-level execution)
• SDK methods (language-level execution)

into one authoritative contract that is:

• Human-readable
• Machine-executable
• AI-safe (no guessing, no hallucination)

---

2. Core Design Principles

1. One method = one intent
2. Multiple execution surfaces (HTTP, SDK)
3. Client creation is explicit
4. Descriptions are mandatory
5. No implicit inference
6. Mini-specs are projections, not sources of truth

---

3. Top-Level Structure

VERSION: "2.0.2"

CLIENTS:
METHODS:
STRUCTS:
SOURCES:
DEFAULTS:

Only VERSION and METHODS are required.

---

4. CLIENTS (SDK Construction)

Defines how SDK clients are instantiated.

CLIENTS:
  SampleSdkClient:
    SUMMARY: Primary SDK client
    DESC: Client used to interact with the Sample service
    CONSTRUCTOR:
      TYPE: "instance"
      INPUTS:
        - name: api_key
          TYPE: "STRING"
          REQUIRED: true
          DESC: API key issued by the service

Rules:

• CLIENTS define existence, not usage
• No language imports or syntax allowed

---

5. METHODS (Unified HTTP + SDK)

Each method represents a single logical capability.

METHODS:
  create-user:
    SUMMARY: Create a new user
    DESC: Creates a new user and returns the created entity

    SOURCE: example

    EXECUTION:
      KIND: hybrid        # http | sdk | hybrid
      MODE: async         # sync | async | fire_and_forget

    HTTP:
      METHOD: "POST"
      ENDPOINT: "/users/{id}"
      CONTENT_TYPE: "application/json"
      ACCEPT: "application/json"
      HEADERS:
        Authorization:
          TYPE: "STRING"
          DESC: Bearer token for authentication
      BODY:
        TYPE: "STRUCT(UserCreateRequest)"

    SDK:
      INTERFACE:
        NAME: createUser
      INVOCATION:
        TYPE: "instance"
        RECEIVER: SampleSdkClient

    INPUTS:
      - name: id
        TYPE: "STRING"
        REQUIRED: true
        LOCATION: "path"
        DESC: Unique user identifier
      - name: email
        TYPE: "STRING"
        REQUIRED: true
        LOCATION: "body"
        DESC: Email address of the user
      - name: name
        TYPE: "STRING"
        REQUIRED: false
        LOCATION: "body"
        DESC: Full name of the user
      - name: request_id
        TYPE: "STRING"
        REQUIRED: false
        LOCATION: "header"
        DESC: Optional request correlation ID

    RETURNS:
      - RETURNTYPE: "STRUCT(User)"
        RETURNVAR: user
        STATUS: "201"
        DESC: Created user object

    ERRORS:
      - TYPE: "ValidationError"
        STATUS: "400"
        WHEN: Invalid input values

---

6. EXECUTION

EXECUTION:
  KIND: http | sdk | hybrid
  MODE: sync | async | fire_and_forget

Defines how and when execution occurs.

---

7. HTTP Section

7.1 ENDPOINT

• Supports path parameters using {param} syntax
• Path parameters must be declared in INPUTS with LOCATION: path

7.2 BODY

BODY:
  TYPE: STRUCT(RequestBody)

Defines request body structure.

7.3 BODYTYPE (Optional)

BODYTYPE: "json" | "form-data" | "x-www-form-urlencoded"

If omitted, defaults to "json".

---

8. INPUTS

- name: limit
  TYPE: "NUMBER"
  REQUIRED: false
  DEFAULT: 10
  LOCATION: "query"
  DESC: Maximum number of items to return

LOCATION (Required for HTTP)

LOCATION	Meaning
path	URL path parameter
query	Query string parameter
body	HTTP request body
header	HTTP header

---

9. RETURNS

RETURNS:
  - RETURNTYPE: STRUCT(User)
    RETURNVAR: user
    STATUS: "200"
    DESC: Returned user object

Streaming Returns

RETURNTYPE: "STREAM(Event)"

---

10. ERRORS

ERRORS:
  - TYPE: "NotFoundError"
    STATUS: "404"
    WHEN: Resource does not exist

Errors are descriptive, not executable.

---

11. STRUCTS

STRUCTS:
  User:
    DESC: Represents a system user
    FIELDS:
      - name: id
        TYPE: "STRING"
        REQUIRED: true
        DESC: Unique identifier
      - name: email
        TYPE: "STRING"
        REQUIRED: true
        DESC: Email address
      - name: name
        TYPE: "STRING"
        REQUIRED: false
        DESC: Display name

---

12. Pagination (Optional)

RETURNS:
  - RETURNTYPE: "STRUCT(UserList)"
    RETURNVAR: users
    PAGINATION:
      TYPE: cursor      # cursor | offset | page | iterator
      CURSOR_FIELD: next_cursor

---

13. SOURCES

SOURCES:
  example:
    KIND: package
    LOCATOR:
      npm: example-sdk
      python: example_sdk

Informational only.

---

14. DEFAULTS

DEFAULTS:
  w_base_url: "https://api.example.com"

---

15. Void / Empty Returns

If a method returns no value:

• Omit RETURNS
• The method is treated as void

---

16. Relationship to Mini-Wrekenfiles

• Full Wrekenfile = authoritative source of truth
• Mini-Wrekenfile = usage-focused projection
• Mini files must never redefine CLIENTS, STRUCTS, or HTTP details

---

17. AI & Code Generation Rules (Normative)

Consumers of this spec MUST:

1. Never infer missing fields
2. Respect INPUTS.LOCATION
3. Never invent client initialization
4. Generate direct calls only
5. Treat this spec as authoritative

---

18. License

MIT

A Wreken Description (WRD) formally describes the surface of an API integration and its semantics. It is composed of an entry document, which must be a Wreken Document, and any/all of its referenced documents. A WRD uses and conforms to the Wreken spec, and MUST contain at least one METHODS field.

Wreken Document

A Wreken Document is a YAML document that conforms to the Wreken spec. A Wreken Document compatible with WRS 2.0.2 contains a required VERSION field which designates the version of the WRS that it uses.

Wrekenfile

A Wrekenfile is a Wreken Document stored in a file named Wrekenfile.yaml or Wrekenfile.yml. The YAML format is mandatory for Wrekenfiles.

Schema

A "schema" is a formal description of syntax and structure. This document serves as the schema for the Wreken spec format, which uses YAML syntax.

Object

When capitalized, the word "Object" refers to any of the Objects that are named by section headings in this document.

Path Templating

Path templating refers to the usage of template expressions, delimited by curly braces ({}), to mark a section of a URL path as replaceable using path parameters.

Each template expression in the path MUST correspond to a path parameter that is included in the Path Item itself and/or in each of the Path Item's Operations. An exception is if the path item is empty, for example due to ACL constraints, matching path parameters are not required.

The value for these path parameters MUST NOT contain any unescaped "generic syntax" characters described by RFC3986: forward slashes (/), question marks (?), or hashes (#).

Media Types

Media type definitions are spread across several resources. The media type definitions SHOULD be in compliance with RFC6838.

Some examples of possible media type definitions:

  text/plain; charset=utf-8
  application/json
  application/vnd.github+json
  application/vnd.github.v3+json
  application/vnd.github.v3.raw+json
  application/vnd.github.v3.text+json
  application/vnd.github.v3.html+json
  application/vnd.github.v3.full+json
  application/vnd.github.v3.diff
  application/vnd.github.v3.patch

HTTP Status Codes

The HTTP Status Codes are used to indicate the status of the executed operation. Status codes SHOULD be selected from the available status codes registered in the IANA Status Code Registry.

Case Sensitivity

As most field names and values in the Wreken spec are case-sensitive, this document endeavors to call out any case-insensitive names and values. However, the case sensitivity of field names and values that map directly to HTTP concepts follow the case sensitivity rules of HTTP, even if this document does not make a note of every concept.

Undefined and Implementation-Defined Behavior

This specification deems certain situations to have either undefined or implementation-defined behavior.

Behavior described as undefined is likely, at least in some circumstances, to result in outcomes that contradict the specification. This description is used when detecting the contradiction is impossible or impractical. Implementations MAY support undefined scenarios for historical reasons, including ambiguous text in prior versions of the specification. This support might produce correct outcomes in many cases, but relying on it is NOT RECOMMENDED as there is no guarantee that it will work across all tools or with future specification versions, even if those versions are otherwise strictly compatible with this one.

Behavior described as implementation-defined allows implementations to choose which of several different-but-compliant approaches to a requirement to implement. This documents ambiguous requirements that API description authors are RECOMMENDED to avoid in order to maximize interoperability. Unlike undefined behavior, it is safe to rely on implementation-defined behavior if and only if it can be guaranteed that all relevant tools support the same behavior.

Specification

Versions

The Wreken spec is versioned using a major.minor.patch versioning scheme. The major.minor.patch portion of the version string (for example 2.0.2) SHALL designate the WRS feature set. Tooling which supports WRS 2.0.2 SHOULD be compatible with all WRS 2.0.2.* versions.

Occasionally, non-backwards compatible changes may be made in minor versions of the WRS where impact is believed to be low relative to the benefit provided.

Format

A Wreken Document that conforms to the Wreken spec is a YAML document. Wrekenfiles (files named Wrekenfile.yaml or Wrekenfile.yml) MUST use YAML format.

For example, if a field has an array value, the YAML array representation will be used:

field: [1, 2, 3]

All field names in the specification are case sensitive. This includes all fields that are used as keys in a map, except where explicitly noted that keys are case insensitive.

The schema exposes two types of fields: fixed fields, which have a declared name, and patterned fields, which have a declared pattern for the field name.

Patterned fields MUST have unique names within the containing object.

YAML version 1.2 is RECOMMENDED along with some additional constraints:

• Tags MUST be limited to those allowed by the YAML core schema ruleset, which defines a subset of the YAML syntax.
• Keys used in YAML maps MUST be limited to a scalar string, as defined by the YAML Failsafe schema ruleset.

Note: While APIs are described by Wreken Descriptions in YAML format, the API request and response bodies and other content are not required to be YAML.

Wreken Description Structure

A Wreken Description (WRD) MAY be made up of a single YAML document or be divided into multiple, connected parts at the discretion of the author. In the latter case, Reference Object, Path Item Object and Schema Object $ref fields, as well as the Link Object operationRef field, and the URI form of the Discriminator Object mapping field, are used to identify the referenced components.

File Rules

For Wrekenfiles (files named Wrekenfile.yaml or Wrekenfile.yml):

1. Accepted filenames: Wrekenfile.yaml or Wrekenfile.yml
2. YAML format is mandatory
3. Focus on REST APIs and SDK methods
4. OpenAPI / Swagger support is optional and external

Data Model

Wreken Document

This is the root document object of the Wreken spec.

Fixed Fields

Field Name	Type	Description
VERSION	string	REQUIRED. This string MUST be the version number of the Wreken spec that the Wreken document uses. The VERSION field SHOULD be used by tooling to interpret the Wreken document. This is not related to the API info.version string.
DEFAULTS	Defaults Object	OPTIONAL. Global constants and environment variables available across the entire workflow.
SOURCES	Sources Object	OPTIONAL. Defines where symbols (classes, functions, clients) originate from, without leaking language-specific import syntax.
UTILITIES	Utilities Object	OPTIONAL. Side-effect-free helper functions that do not depend on other Wrekenfile callables.
CONSTRUCTORS	Constructors Object	OPTIONAL. Constructors and factories that create instances required by instance methods.
METHODS	Methods Object	REQUIRED. The available methods for this library.
STRUCTS	Structs Object	OPTIONAL. The data models used by the library.
TESTS	Tests Object	OPTIONAL. Test cases for the library.

Patterned Fields

Field Pattern	Type	Description
^x-	Any	Allows extensions to the Wreken spec. The field name MUST begin with x-, for example, x-internal-id. The value can be null, a primitive, an array or an object. Can have any valid YAML value.

Defaults Object

The Defaults Object contains global constants and environment variables available across the entire workflow.

Fixed Fields

Field Name	Type	Description
w_base_url	string	OPTIONAL. Base URL for API endpoints. When defined, it will be prepended to ENDPOINT values in METHODS. MUST NOT contain a trailing slash.

Patterned Fields

Field Pattern	Type	Description
^[A-Za-z][A-Za-z0-9_-]*$	Any	Default values for constants and environment variables. The field name MUST match the pattern ^[A-Za-z][A-Za-z0-9_-]*$. Method-level DEFAULTS override global DEFAULTS.

Sources Object

The Sources Object defines where symbols (classes, functions, clients) originate from, without leaking language-specific import syntax.

Purpose

• Decouples what is used from how it is imported
• Enables correct multi-language code generation
• Allows import de-duplication across workflows

Rules

• SOURCES define origins, not syntax
• Methods and constructors may reference exactly one SOURCE (or an array, rarely)
• HTTP-only methods typically do not require a SOURCE

Patterned Fields

Field Pattern	Type	Description
^[A-Za-z][A-Za-z0-9_-]*$	Source Object	The source alias. MUST match the pattern ^[A-Za-z][A-Za-z0-9_-]*$.

Source Object

The Source Object defines the origin of symbols.

Fixed Fields

Field Name	Type	Description
KIND	string	REQUIRED. The kind of source. MUST be one of: package, runtime, local.
IDENTIFIERS	array[string]	REQUIRED. List of symbol names that originate from this source.
LOCATOR	Locator Object	REQUIRED. Language-specific import paths.

Locator Object

The Locator Object contains language-specific import paths.

Patterned Fields

Field Pattern	Type	Description
^[a-z]+$	string	Language identifier (e.g., npm, pypi, go, maven) and the corresponding import path for that language.

Utilities Object

The Utilities Object contains side-effect-free helper functions that do not depend on other Wrekenfile callables.

Rules

• No INPUTS dependency on other methods
• Used for timestamps, UUIDs, hashing, etc.

Patterned Fields

Field Pattern	Type	Description
^[A-Za-z][A-Za-z0-9_-]*$	Utility Object	The utility name. MUST match the pattern ^[A-Za-z][A-Za-z0-9_-]*$.

Utility Object

The Utility Object describes a single utility function.

Fixed Fields

Field Name	Type	Description
SUMMARY	string	REQUIRED. One-line, imperative description of what the utility does.
RETURNS	Returns Object	REQUIRED. Return type and variable name.

Constructors Object

The Constructors Object contains constructors and factories that create instances required by instance methods.

Key Concepts

• Covers new Class(), Class(), NewClass() across languages
• Syntax-free and semantic

Patterned Fields

Field Pattern	Type	Description
^[A-Za-z][A-Za-z0-9_-]*$	Constructor Object	The constructor name. MUST match the pattern ^[A-Za-z][A-Za-z0-9_-]*$.

Constructor Object

The Constructor Object describes a single constructor or factory.

Fixed Fields

Field Name	Type	Description
SUMMARY	string	REQUIRED. One-line, imperative description of what the constructor does.
SOURCE	string	OPTIONAL. Reference to a SOURCE alias defined in the SOURCES section.
INTERFACE	Interface Object	REQUIRED. The callable symbol name in the SDK.
INVOCATION	Invocation Object	REQUIRED. Defines how the callable is invoked.
INPUTS	Inputs Object	OPTIONAL. Input parameters.
RETURNS	Returns Object	REQUIRED. Return type and variable name.

Methods Object

The Methods Object contains the available methods for the library.

Patterned Fields

Field Pattern	Type	Description
^[A-Za-z][A-Za-z0-9_-]*$	Method Object	The method name (alias). MUST match the pattern ^[A-Za-z][A-Za-z0-9_-]*$.

Method Object

The Method Object describes a single method available in the library.

Each method must explicitly define:

• Callable identity
• Invocation semantics
• Execution behavior

Fixed Fields

Field Name	Type	Description
SUMMARY	string	REQUIRED. One-line, imperative description of what the method does.
DESC	string	OPTIONAL. Extended behavioral description.
SOURCE	string	OPTIONAL. Reference to a SOURCE alias defined in the SOURCES section. Required for SDK methods, typically not needed for pure HTTP methods.
INTERFACE	Interface Object	OPTIONAL. The callable symbol name in the SDK. Mandatory for SDK/function methods, forbidden for pure HTTP methods.
INVOCATION	Invocation Object	REQUIRED. Defines how the callable is invoked.
REQUIRES	array[Requires Object]	OPTIONAL. Explicit dependencies that must exist before invocation.
EXECUTION	Execution Object	REQUIRED. Defines completion semantics.
ASYNC	Async Object	OPTIONAL. Required when EXECUTION.MODE is async. Defines async behavior details.
INPUTS	Inputs Object	OPTIONAL. Input parameters.
DEFAULTS	Defaults Object	OPTIONAL. Method-specific defaults overriding global DEFAULTS.
HTTP	Http Object	OPTIONAL. HTTP configuration for API methods.
RETURNS	Returns Object	OPTIONAL. Return type and variable name. Should be omitted for functions that return void/None/undefined.
ERRORS	array[Error Object]	OPTIONAL. Defines failure behavior and error types that may be raised/thrown/returned.

Interface Object

The Interface Object defines the callable symbol name in the SDK.

Fixed Fields

Field Name	Type	Description
NAME	string	REQUIRED. The function or method name. No arguments allowed, no language keywords.

Rules

• No arguments allowed
• No language keywords
• Forbidden for pure HTTP methods

Invocation Object

The Invocation Object defines how the callable is invoked.

Fixed Fields

Field Name	Type	Description
TYPE	string	REQUIRED. The invocation type. MUST be one of: instance, static, function, constructor.
RECEIVER	string	OPTIONAL. Required when TYPE is instance or static. The struct name that receives the method call.

Requires Object

The Requires Object defines explicit dependencies that must exist before invocation.

Fixed Fields

Field Name	Type	Description
INSTANCE	string	REQUIRED. The struct name of an instance that must exist before this method can be called.

Execution Object

The Execution Object defines completion semantics.

Fixed Fields

Field Name	Type	Description
MODE	string	REQUIRED. The execution mode. MUST be one of: sync, async, fire_and_forget.

Async Object

The Async Object defines async behavior details. Required when EXECUTION.MODE is async.

Fixed Fields

Field Name	Type	Description
RETURNS	string	REQUIRED. The async return type. MUST be one of: result, job, stream.
RESULT	Result Object	OPTIONAL. Required when RETURNS is result. Defines the result type.

Async Return Types

RETURNS	Meaning
result	Awaitable final value
job	Long-running operation requiring polling
stream	Continuous stream of items

Result Object

The Result Object defines the result type for async operations.

Fixed Fields

Field Name	Type	Description
TYPE	string	REQUIRED. The type of the result (e.g., STRUCT(PAYMENT), STRING, []INT).

Inputs Object

The Inputs Object contains input parameters for methods.

Simple Form

When using the simple form, REQUIRED defaults to true:

INPUTS:
  - userid: INT
  - amount: FLOAT

Extended Form

The extended form allows specifying optional parameters with REQUIRED and DEFAULT:

INPUTS:
  - userid:
      TYPE: INT
      REQUIRED: true
  - coupon:
      TYPE: STRING
      REQUIRED: false
  - currency:
      TYPE: STRING
      REQUIRED: false
      DEFAULT: "USD"

Rules

• REQUIRED: true is the default if not specified
• Optional parameters enable correct form generation, validation, and call signatures
• DEFAULTS section can also provide default values (method-level overrides global)

Http Object

The Http Object contains HTTP configuration for API methods.

Fixed Fields

Field Name	Type	Description
METHOD	string	REQUIRED. HTTP method. MUST be one of: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS.
ENDPOINT	string	REQUIRED. URL endpoint path. May include path parameters using {param} syntax. The w_base_url from DEFAULTS is automatically prepended.
HEADERS	Headers Object	OPTIONAL. HTTP headers to send with the request.
BODYTYPE	string	OPTIONAL. Body type. MUST be one of: raw, form-data, x-www-form-urlencoded.

Notes

• w_base_url is automatically prepended
• HTTP methods default to EXECUTION.MODE: async

Headers Object

The Headers Object contains HTTP headers to send with the request.

Patterned Fields

Field Pattern	Type	Description
^[A-Za-z][A-Za-z0-9_-]*$	string	Header name and value. The header name MUST match the pattern ^[A-Za-z][A-Za-z0-9_-]*$. The value may reference DEFAULTS variables.

Returns Object

The Returns Object contains return type information for methods.

Fixed Fields

Field Name	Type	Description
RETURNTYPE	string	REQUIRED. Return type (e.g., STRING, INT, FLOAT, BOOL, STRUCT(PAYMENT), []STRING, map[STRING]INT).
RETURNVAR	string	OPTIONAL. Variable name for the return value.
PAGINATION	Pagination Object	OPTIONAL. Pagination hints for paginated/iterable return types.

Rules

• RETURNS section should be omitted for functions that return void/None/undefined
• If a function has no return value, the RETURNS section should not be included
• RETURNS is only needed when the function actually returns a value
• Functions that return void/None/undefined are considered to have no return value

Pagination Object

The Pagination Object provides hints for paginated/iterable return types.

Fixed Fields

Field Name	Type	Description
TYPE	string	REQUIRED. The pagination type. MUST be one of: cursor, offset, page, iterator.
CURSOR_FIELD	string	OPTIONAL. Field name containing the cursor/continuation token. Required when TYPE is cursor.
OFFSET_FIELD	string	OPTIONAL. Field name containing offset value. Required when TYPE is offset.
PAGE_SIZE_FIELD	string	OPTIONAL. Field name containing page size. Required when TYPE is page.

This enables LLMs to generate proper iteration loops, not one-shot calls.

Error Object

The Error Object defines failure behavior and error types that may be raised/thrown/returned.

Fixed Fields

Field Name	Type	Description
TYPE	string	REQUIRED. The error type. Should reference a STRUCT defined in the STRUCTS section (or be ANY for untyped errors).
WHEN	string	REQUIRED. A human-readable description of when this error occurs.

Rules

• ERRORS are optional but recommended for methods that can fail
• TYPE should reference a STRUCT defined in the STRUCTS section (or be ANY for untyped errors)
• WHEN provides a human-readable description of when this error occurs
• Multiple error types can be specified for different failure scenarios

Language Mapping

• Go: error return values → ERRORS section
• Java: throws declarations → ERRORS section
• TypeScript: Promise rejections → ERRORS section
• Python: raise exceptions → ERRORS section

Structs Object

The Structs Object contains data model definitions for the library.

Guidelines

• STRUCTS are optional, but strongly recommended for all STRUCT() references
• Return types (RETURNS section) SHOULD have definitions when available in source code
• Only structs with at least one field should be included
• Empty structs (interfaces without fields, abstract types) should be omitted
• External library types (standard library, third-party dependencies) should be documented with source information

Patterned Fields

Field Pattern	Type	Description
^[A-Za-z][A-Za-z0-9_-]*$	Struct Object	The struct name. MUST match the pattern ^[A-Za-z][A-Za-z0-9_-]*$.

Struct Object

The Struct Object describes a single data structure.

Struct Field Structure

Each struct field can have the following properties:

STRUCTS:
  LIBRARY_CONFIG:
    - name: api_key
      type: STRING
      REQUIRED: true  # Optional, defaults to true
      comment: "Optional comment describing the field"  # Optional, for documentation

External Types

External library types (types from dependencies, standard libraries, or third-party packages) should be documented with their source information:

1. Document with source package (Recommended): When a struct type is referenced but not defined in the parsed source code, parsers should add it to STRUCTS with a comment field indicating its source:

   STRUCTS:
     Config:
       - name: _note
         type: STRING
         comment: "External type from package: aws-sdk-go or similar config library"
     
     PrivateKey:
       - name: _note
         type: STRING
         comment: "External type from package: crypto/rsa or crypto/ecdsa"

2. Omit (Alternative for truly unknown types):

   • Types from standard libraries may be omitted if source cannot be determined
   • Types from third-party libraries may be omitted if definition and source are unavailable

3. Use ANY (Fallback for truly unknown types):

   RETURNS:
     - RETURNTYPE: "ANY"  # Instead of STRUCT(UnknownType)

External Type Documentation Rules

• Parsers should attempt to extract source package information from qualified type names (e.g., crypto/rsa.PrivateKey → package: crypto/rsa)
• When source package is available, it should be included in the comment field
• When source package is not available, parsers may infer common external types (e.g., PrivateKey → likely from crypto library)
• The _note field with type STRING is used as a placeholder to satisfy the "at least one field" requirement while documenting external types

Note: Parsers should prioritize extracting definitions from source code. External types that cannot be extracted should be documented with their source information when possible, or omitted if source cannot be determined.

Patterned Fields

Field Pattern	Type	Description
^[A-Za-z][A-Za-z0-9_-]*$	Struct Field Object	Field name and definition. MUST match the pattern ^[A-Za-z][A-Za-z0-9_-]*$.

Struct Field Object

The Struct Field Object describes a single field in a struct.

Fixed Fields

Field Name	Type	Description
name	string	REQUIRED. The field name.
type	string	REQUIRED. The field type (e.g., STRING, INT, FLOAT, BOOL, STRUCT(OTHER), []STRING, map[STRING]INT).
REQUIRED	boolean	OPTIONAL. Whether the field is required. Defaults to true if not specified.
comment	string	OPTIONAL. Optional comment describing the field. Used for documentation and external type source information.

Tests Object

The Tests Object contains test cases for the library.

Fixed Fields

Field Name	Type	Description
NLP	array[string]	OPTIONAL. Natural language test cases used for validation and demo generation.

Type System

Primitive Types

The Wreken spec defines the following primitive types:

• STRING: Text/string values
• INT: Integer numbers
• FLOAT: Floating-point numbers
• BOOL: Boolean values (true/false)
• TIMESTAMP: Date/time values
• DATE: Date values
• TIME: Time values
• NULL: Null value
• UNDEFINED: Undefined value
• VOID: No return value (for functions that return nothing)
• ANY: Unknown or dynamic type
• OBJECT: Generic object/dictionary with unknown structure (for truly generic key-value pairs)

Composite Types

Arrays

• []TYPE: Array/list of TYPE
  • Example: []STRING (array of strings), []INT (array of integers)
  • Example: []STRUCT(User) (array of User structs)

Maps

• map[KEY]VALUE: Map/dictionary with KEY type keys and VALUE type values
  • Example: map[STRING]STRING (dictionary with string keys and string values)
  • Example: map[STRING]INT (dictionary with string keys and integer values)
  • Example: map[STRING]STRUCT(User) (dictionary with string keys and User struct values)
  • Example: map[STRING]ANY (dictionary with string keys and any type values)

Structs

• STRUCT(Name): Reference to a struct defined in the STRUCTS section
  • Example: STRUCT(PAYMENT) (reference to PAYMENT struct)
  • Example: STRUCT(USER_CONFIG) (reference to USER_CONFIG struct)

Type Examples

Language mappings:

• Python: Dict[str, str] → map[STRING]STRING
• Python: Dict[str, Any] → map[STRING]ANY or OBJECT
• Python: List[str] → []STRING
• Python: object → OBJECT
• Java: Map<String, String> → map[STRING]STRING
• Java: List<String> → []STRING
• TypeScript: Record<string, string> → map[STRING]STRING
• TypeScript: string[] → []STRING
• Go: map[string]string → map[STRING]STRING
• Go: []string → []STRING

Method Overloading / Variants

SDKs often expose multiple methods with the same name but different parameter shapes.

Recommended approach:

Model overloads as separate aliases with the same INTERFACE name:

METHODS:
  create-user-basic:
    SUMMARY: "Create a user with minimal parameters"
    INTERFACE:
      NAME: create
    INPUTS:
      - userid: STRING
      - email: STRING

  create-user-advanced:
    SUMMARY: "Create a user with full options"
    INTERFACE:
      NAME: create
    INPUTS:
      - options: STRUCT(USER_OPTIONS)

This approach:

• Keeps the spec simple and flat
• Allows parsers to extract each variant independently
• Enables LLMs to choose the appropriate variant based on available inputs
• Maintains clear separation between alias (unique) and interface name (can repeat)

Explicitly Forbidden

The following must never appear in a Wrekenfile:

• new
• await
• Language-specific async keywords
• Inline executable code
• Parentheses in INTERFACE definitions
• Language-specific import syntax (import, require, using, etc.)

Examples

Minimal Example

VERSION: "2.0.2"

DEFAULTS:
  userid: 1
  cartid: 1
  amount: 100.00
  bearer_token: "BEARER abcd"

METHODS:
  make-payment:
    SUMMARY: "Make a payment for a product"
    
    INTERFACE:
      NAME: make_payment
    
    INVOCATION:
      TYPE: "function"
    
    EXECUTION:
      MODE: async
    
    ASYNC:
      RETURNS: result
      RESULT:
        TYPE: "STRUCT(PAYMENT)"
    
    INPUTS:
      - userid:
          TYPE: "INT"
          REQUIRED: true
      - cartid:
          TYPE: "INT"
          REQUIRED: true
      - amount:
          TYPE: "FLOAT"
          REQUIRED: true
      - nonce:
          TYPE: "STRING"
          REQUIRED: true
      - cardtype:
          TYPE: "STRING"
          REQUIRED: false
    
    DEFAULTS:
      cardtype: "Master"
      amount: 100.00
    
    RETURNS:
      - RETURNTYPE: "STRUCT(PAYMENT)"
        RETURNVAR: payment_status
    
    ERRORS:
      - TYPE: "STRUCT(PAYMENT_ERROR)"
        WHEN: "Card is declined or insufficient funds"

STRUCTS:
  PAYMENT:
    - name: id
      type: STRING
      REQUIRED: true
    - name: amount
      type: FLOAT
      REQUIRED: true
    - name: status
      type: STRING
      REQUIRED: true
    - name: created_at
      type: TIMESTAMP
      REQUIRED: true

  PAYMENT_ERROR:
    - name: code
      type: STRING
      REQUIRED: true
    - name: message
      type: STRING
      REQUIRED: true

TESTS:
  NLP:
    - Generate code to make a payment using Visa card and get the payment details for the generated paymentid
    - Get all payment methods

Full Example

VERSION: "2.0.2"

DEFAULTS:
  userid: 1
  cartid: 1
  amount: 100.00
  bearer_token: "BEARER abcd"
  some_val: "SOME VALUE"
  w_base_url: "https://api.example.com"

SOURCES:
  library-sdk:
    KIND: package
    IDENTIFIERS:
      - Library
      - make_payment
      - get_paymentDetails_by_id
    LOCATOR:
      npm: "@payments/library"
      pypi: "payments_library"
      go: "gitlab.com/vendor/package"
      maven: "com.payments:library"

UTILITIES:
  current-date:
    SUMMARY: "Generate the current timestamp"
    RETURNS:
      - RETURNTYPE: "TIMESTAMP"
        RETURNVAR: currentDate

CONSTRUCTORS:
  library:
    SUMMARY: "Initialize the payment library client"
    
    SOURCE: library-sdk
    
    INTERFACE:
      NAME: Library
    
    INVOCATION:
      TYPE: "constructor"
    
    INPUTS:
      - config: STRUCT(LIBRARY_CONFIG)
    
    RETURNS:
      - RETURNTYPE: "STRUCT(LIBRARY)"
        RETURNVAR: lib

METHODS:
  nonce:
    SUMMARY: "Generate one unique key for the transactions"
    
    INTERFACE:
      NAME: nonce
    
    INVOCATION:
      TYPE: "function"
    
    EXECUTION:
      MODE: sync
    
    RETURNS:
      - RETURNTYPE: "STRING"
        RETURNVAR: nonceVal

  make-payment:
    SUMMARY: "Make a payment for a product"
    
    SOURCE: library-sdk
    
    INTERFACE:
      NAME: make_payment
    
    INVOCATION:
      TYPE: "instance"
      RECEIVER: LIBRARY
    
    REQUIRES:
      - INSTANCE: LIBRARY
    
    EXECUTION:
      MODE: async
    
    ASYNC:
      RETURNS: result
      RESULT:
        TYPE: "STRUCT(PAYMENT)"
    
    INPUTS:
      - userid:
          TYPE: "INT"
          REQUIRED: true
      - cartid:
          TYPE: "INT"
          REQUIRED: true
      - amount:
          TYPE: "FLOAT"
          REQUIRED: true
      - nonce:
          TYPE: "STRING"
          REQUIRED: true
      - cardtype:
          TYPE: "STRING"
          REQUIRED: true
      - coupon:
          TYPE: "STRING"
          REQUIRED: false
      - currency:
          TYPE: "STRING"
          REQUIRED: false
          DEFAULT: "USD"
    
    DEFAULTS:
      cardtype: "Master"
      amount: 100.00
      nonce: nonceVal
    
    RETURNS:
      - RETURNTYPE: "STRUCT(PAYMENT)"
        RETURNVAR: payment_status
    
    ERRORS:
      - TYPE: "STRUCT(PAYMENT_ERROR)"
        WHEN: "Card is declined or insufficient funds"
      - TYPE: "STRUCT(AUTH_ERROR)"
        WHEN: "Invalid API key or expired session"

  payment-details-by-id:
    SUMMARY: "Get payment details by ID"
    
    SOURCE: library-sdk
    
    INTERFACE:
      NAME: get_paymentDetails_by_id
    
    INVOCATION:
      TYPE: "instance"
      RECEIVER: LIBRARY
    
    REQUIRES:
      - INSTANCE: LIBRARY
    
    EXECUTION:
      MODE: sync
    
    INPUTS:
      - userid:
          TYPE: "INT"
          REQUIRED: true
      - paymentid:
          TYPE: "STRING"
          REQUIRED: false
    
    DEFAULTS:
      paymentid: payment_status.uid
    
    RETURNS:
      - RETURNTYPE: "[]STRUCT(PAYMENT)"

  user-payment-details:
    SUMMARY: "Get details of user's specific payment"
    
    EXECUTION:
      MODE: async
    
    ASYNC:
      RETURNS: result
      RESULT:
        TYPE: "[]STRUCT(PAYMENT)"
    
    HTTP:
      METHOD: "POST"
      ENDPOINT: "/payment-details"
      HEADERS:
        Authorization: bearer_token
        CustomHeader: some_val
      BODYTYPE: "raw"
    
    INPUTS:
      - userid:
          TYPE: "INT"
          REQUIRED: true
    
    RETURNS:
      - RETURNTYPE: "[]STRUCT(PAYMENT)"

  payment-methods:
    SUMMARY: "Get all available payment methods"
    
    EXECUTION:
      MODE: async
    
    ASYNC:
      RETURNS: result
      RESULT:
        TYPE: "[]STRUCT(PAYMENT_METHOD)"
    
    HTTP:
      METHOD: "GET"
      ENDPOINT: "/payment-methods"
      HEADERS:
        Authorization: bearer_token
        CustomHeader: some_val
    
    RETURNS:
      - RETURNTYPE: "[]STRUCT(PAYMENT_METHOD)"
        RETURNVAR: methods
        PAGINATION:
          TYPE: "cursor"
          CURSOR_FIELD: next_cursor

STRUCTS:
  LIBRARY_CONFIG:
    - name: api_key
      type: STRING
      REQUIRED: true
    - name: environment
      type: STRING
      REQUIRED: false
      comment: "Environment: 'production' or 'sandbox'"

  LIBRARY:
    - name: name
      type: STRING
      REQUIRED: true
    - name: version
      type: STRING
      REQUIRED: true
    - name: surname
      type: STRING
      REQUIRED: true
    - name: age
      type: INT
      REQUIRED: true
    - name: pets
      type: []STRING
      REQUIRED: true
    - name: watches
      type: []STRUCT(WATCHES)
      REQUIRED: false

  WATCHES:
    - name: make
      type: STRING
      REQUIRED: true
    - name: price
      type: FLOAT
      REQUIRED: true
    - name: year
      type: INT
      REQUIRED: false

  PAYMENT:
    - name: id
      type: STRING
      REQUIRED: true
    - name: amount
      type: FLOAT
      REQUIRED: true
    - name: status
      type: STRING
      REQUIRED: true
    - name: created_at
      type: TIMESTAMP
      REQUIRED: true

  PAYMENT_METHOD:
    - name: id
      type: STRING
      REQUIRED: true
    - name: name
      type: STRING
      REQUIRED: true
    - name: type
      type: STRING
      REQUIRED: true
    - name: next_cursor
      type: STRING
      REQUIRED: false
      comment: "Cursor for pagination"

  PAYMENT_ERROR:
    - name: code
      type: STRING
      REQUIRED: true
    - name: message
      type: STRING
      REQUIRED: true

  AUTH_ERROR:
    - name: code
      type: STRING
      REQUIRED: true
    - name: message
      type: STRING
      REQUIRED: true

TESTS:
  NLP:
    - Generate code to make a payment using Visa card and get the payment details for the generated paymentid
    - Get all payment methods

Changelog

• 2.0.2 — Current version with unified HTTP + SDK execution, enhanced AI safety, and comprehensive semantic modeling
• 2.0.0 — Major restructure with SOURCES, UTILITIES, CONSTRUCTORS, and enhanced METHOD structure
• 1.2 — Previous version with INIT, EXT, ENTRY structure
• 1.0 — Initial specification draft

Notes

This specification intentionally mirrors the clarity and structure of established API specs like OpenAPI while focusing on API integrations, SDK semantics, and transformation workflows. Implementations should provide helpful error messages for validation failures and preserve unknown fields to maintain forward compatibility.

Wrekenfile v2.0.2 models callable identity, dependency, and execution semantics separately. This separation is what enables:

• Multi-language code generation
• Deterministic AST → spec mapping
• Reliable LLM reasoning
• Workflow planning and MCP integration

Changes from v2.0.0

1. RETURNS section: Clarified that void/None/undefined functions should omit RETURNS section
2. STRUCTS section: Added guidance on external types, empty structs, and return type definitions
3. Primitive types: Added VOID to the primitive types list
4. INPUTS section: Added REQUIRED field to support optional parameters (defaults to true)
5. ERRORS section: Added optional ERRORS section to model failure behavior and error types
6. RETURNS section: Added optional PAGINATION hints for paginated/iterable return types
7. Method overloading: Documented recommended approach for handling method variants/overloads
8. Clarifications: Enhanced guidance for parsers and code generators
9. External struct documentation: Added comment field to struct fields for documenting external types with their source packages

Real-World SDK Handling

This version addresses critical gaps that appear when parsing real-world SDKs:

• Error semantics: Models exceptions, error returns, and typed errors across languages
• Optional parameters: Enables correct form generation, validation, and call signatures
• Method overloading: Handles multiple methods with same name but different parameter shapes
• Pagination: Supports cursors, offsets, and iterators for list-based operations

These additions ensure workflows are not optimistically wrong and enable proper error handling, validation, and iteration patterns.

This version should be treated as the baseline moving forward.