AgStack Foundation API Rules

# agstack — Spectral ruleset (strengthened)
# Plain Spectral. Existing hand-authored rules preserved; measured rules added
# from this provider's own OpenAPI conventions by strengthen_ruleset.py,
# then self-validated against the spec.
#
# Provenance:
#   - servers-https-only: 100% of servers already https (error)
#   - servers-expected-domain: 1/1 servers on agstack.org
#   - path-params-casing: snake @ 100% (n=141)
#   - query-params-casing: snake @ 88% (n=331)
#   - schema-names-casing: pascal @ 99% (n=81)
#   - schema-properties-casing: camel @ 56% (n=627)
#   - operation-security-required: 185/191 ops declare per-op security
#   - error-schema-defined: HTTPValidationError
#   - merge: kept 16 existing, added 9 measured, upgraded 0
#   - added: servers-https-only, servers-expected-domain, path-params-casing, query-params-casing, schema-names-casing, schema-properties-casing, security-schemes-defined, error-schema-defined, no-empty-descriptions
extends:
  - spectral:oas
rules:
  agstack-operation-summary-title-case:
    description: Operation summaries should use Title Case
    severity: warn
    given: $.paths[*][*].summary
    then:
      function: pattern
      functionOptions:
        match: ^[A-Z]
  agstack-operationid-defined:
    description: All operations must define an operationId
    severity: error
    given: $.paths[*][get,post,put,delete,patch]
    then:
      field: operationId
      function: defined
  agstack-response-200-defined:
    description: All operations must define a successful response
    severity: error
    given: $.paths[*][*].responses
    then:
      function: truthy
  agstack-response-422-validation-error:
    description: FastAPI operations should document 422 validation errors
    severity: warn
    given: $.paths[*][get,post].responses
    then:
      function: truthy
  agstack-security-bearer-defined:
    description: Protected operations must declare Bearer security
    severity: warn
    given: $.paths[*][post,put,delete,patch]
    then:
      field: security
      function: defined
  agstack-info-version:
    description: API must define a version
    severity: error
    given: $.info
    then:
      field: version
      function: defined
  agstack-info-description:
    description: API must include a description
    severity: warn
    given: $.info
    then:
      field: description
      function: defined
  agstack-server-url-defined:
    description: API must define at least one server URL
    severity: error
    given: $.servers
    then:
      function: length
      functionOptions:
        min: 1
  agstack-schema-type-defined:
    description: Schema components must define a type
    severity: warn
    given: $.components.schemas[*]
    then:
      field: type
      function: defined
  agstack-request-body-content-type:
    description: POST/PUT request bodies should specify application/json content type
    severity: warn
    given: $.paths[*][post,put].requestBody.content
    then:
      function: truthy
  agstack-tags-on-operations:
    description: All operations should have tags for grouping
    severity: warn
    given: $.paths[*][*]
    then:
      field: tags
      function: defined
  agstack-geo-id-format:
    description: Geo ID fields should follow AgStack's 16-character alphanumeric format
    severity: warn
    given: $.components.schemas[*].properties.geo_id
    then:
      function: truthy
  agstack-openapi-version-3:
    description: API must use OpenAPI 3.x
    severity: error
    given: $.openapi
    then:
      function: pattern
      functionOptions:
        match: ^3\.
  agstack-description-field-length:
    description: Operation descriptions should be meaningful (min 10 chars)
    severity: warn
    given: $.paths[*][*].description
    then:
      function: minLength
      functionOptions:
        value: 10
  agstack-geojson-type-field:
    description: GeoJSON schemas must include a type field
    severity: error
    given: $.components.schemas.GeoJSONOut.properties
    then:
      field: type
      function: defined
  agstack-paths-lowercase:
    description: API paths should use lowercase and hyphens
    severity: warn
    given: $.paths
    then:
      function: pattern
      functionOptions:
        match: ^/[a-z0-9/{}_-]+$
  servers-https-only:
    description: Server URLs must use HTTPS.
    severity: error
    given: $.servers[*].url
    then:
      function: pattern
      functionOptions:
        match: ^https://
  servers-expected-domain:
    description: Server URLs should be on the agstack.org domain.
    severity: warn
    given: $.servers[*].url
    then:
      function: pattern
      functionOptions:
        match: agstack\.org
  path-params-casing:
    description: Path parameters should be snake_case (the dominant convention in this API).
    severity: warn
    given: $.paths[*].parameters[?(@.in=='path')].name
    then:
      function: casing
      functionOptions:
        type: snake
  query-params-casing:
    description: Query parameters should be snake_case (the dominant convention in this API).
    severity: warn
    given: $.paths[*][get,post,put,patch,delete].parameters[?(@.in=='query')]
    then:
      field: name
      function: casing
      functionOptions:
        type: snake
  schema-names-casing:
    description: Component schema names should be PascalCase (the dominant convention in this API).
    severity: warn
    given: $.components.schemas
    then:
      field: '@key'
      function: pattern
      functionOptions:
        match: ^[A-Z][A-Za-z0-9]*$
  schema-properties-casing:
    description: Schema properties should be camelCase (the dominant convention in this API).
    severity: info
    given: $.components.schemas[*].properties
    then:
      field: '@key'
      function: pattern
      functionOptions:
        match: ^[a-z][A-Za-z0-9]*$
  security-schemes-defined:
    description: Security schemes should be defined in components.
    severity: warn
    given: $.components
    then:
      field: securitySchemes
      function: truthy
  error-schema-defined:
    description: A shared error schema (HTTPValidationError) should be defined for error payloads.
    severity: warn
    given: $.components.schemas
    then:
      field: HTTPValidationError
      function: truthy
  no-empty-descriptions:
    description: Descriptions must not be empty strings.
    severity: warn
    given: $..description
    then:
      function: truthy