function.yaml

$schema: https://json-schema.org/draft/2020-12/schema
$id: /schemas/function
title: Function schema
type: object

properties:
  shared:
    description: |
      A shared specification of a function.
      You must always create a server and a client property, and merge this into both
      using a reference.
    $ref: '#/$defs/common_properties'
  server:
    description: A server-side specification of a function.
    $ref: '#/$defs/common_properties'
  client:
    description: A client-side specification of a function.
    $ref: '#/$defs/common_properties'

$defs:
  common_properties:
    type: object
    required:
      - name
    properties:
      name:
        type: string
        description: Name of the function.
      pair:
        type: string
        description: Associates this function with another getter or setter function.
      oop:
        $ref: '#/$defs/oop'
      disabled:
          description: |
            Describe why the function was disabled, and if there is an alternative approach;
            or just set the property to "true".
          anyOf:
            - type: string
            - const: true
      meta:
        $ref: '#/$defs/meta'
      description:
        type: string
        description: Describes the functionality provided by the function.
      important_notes:
        type: array
        description: |
          A list of important notes about the function.
          This is a list of things that are important to know about the function, but not
          necessarily related to the function itself.
        items:
          type: string
      notes:
        type: array
        description: List of noteworthy pieces of information for the function.
        items:
          type: string
      preview_images:
        $ref: '#/$defs/preview_images'
      parameters:
        $ref: '#/$defs/parameters'
      ignore_parameters:
        type: array
        description: |
          A list of parameters to remove from the parameters list.
          You should only use this for shared functions, for example where the client function is
          missing a player parameter
        items:
          type: string
          uniqueItems: true
      returns:
        $ref: '#/$defs/returns'
      version:
        description: Version information when the function got added/deprecated/removed.
        $ref: '#/$defs/version'
      issues:
        $ref: '#/$defs/issues'
      examples:
        $ref: '#/$defs/examples'
      see_also:
        type: array
        description: |
          A list of other categories for further reading.
          Every function will implicitly display it's own category in *See Also*, unless you
          introduce this property, then you have to be explicit about it.
        items:
          type: string
          pattern: "^(category):"
          uniqueItems: true
  
  oop:
    type: object
    description: Object-Oriented Programming (OOP) information block for the function.
    required:
      - entity
    properties:
      note:
        type: string
        description: A piece of information to show alongside OOP syntax.
      entity:
        type: string
        description: Name of the element or userdata.
    oneOf:
      - required:
          - method
        properties:
          method:
            type: string
            description: Name of the method.
          static:
            type: boolean
            default: false
            description: If set to true, this method will be marked as static.
          variable:
            type: string
            description: Name of the variable without a leading dot.
      - required:
          - constructor
        properties:
          constructor:
            type: string
            description: Name of the constructor.

  meta:
    type: array
    description: A list of meta properties about the function and it's documentation.
    items:
      type: object
      properties:
        needs_checking:
          type: string
          description: Describe why the function needs checking by another person. What's problematic?

  preview_images:
    type: array
    description: A list of picture assets demonstrating the function.
    items:
      type: object
      required:
        - path
      properties:
        path:
          type: string
          description: A relative or repository-absolute path to an asset file.
        description:
          type: string
          description: Brief summary of the content in the picture.

  parameters:
    type: array
    description: A list of required and optional parameters for the function.
    items:
      type: object
      required:
        - name
        - type
        - description
      properties:
        name:
          type: string
          description: Name of the function parameter.
        type:
          type: string
          description: Type of the function parameter.
        description:
          type: string
          description: Describe the usage, contraints and other useful information about the parameter.
        default:
          type: string
          description: |
            The default value for this parameter, if none was given in the call to the function.
            This property automatically implicitly marks this parameter as optional.
        optional:
          type: boolean
          default: false
          description: If set to true, this parameter is optional.

  returns:
    type: object
    required:
      - values
    properties:
      description:
        type: string
        description: A summary for the return values.
      values:
        type: array
        description: A list of named values returned by the function.
        items:
          type: object
          required:
            - type
            - name
          properties:
            type:
              type: string
              description: Type of the return value.
            name:
              type: string
              description: Name of the return value.

  version:
    type: object
    properties:
      added:
        type: string
        description: Version when this item was added to MTA.
      removed:
        type: string
        description: Version when this item was removed from MTA.
      deprecated:
        type: string
        description: Version when this item was deprecated in MTA.
      replacement:
        type: string
        description: An optional replacement for this item.

  issues:
    type: array
    description: A list of related issues for this function.
    items:
      type: object
      required:
        - id
        - description
      properties:
        id:
          type: integer
          description: Numeric identifier of the GitHub issue.
        description:
          type: string
          description: Description or summary for this GitHub issue.

  examples:
    type: array
    description: A list of source code examples demonstrating the function.
    items:
      type: object
      required:
        - path
      properties:
        path:
          type: string
          description: A relative or repository-absolute path to an example source file.
        description:
          type: string
          description: Description for this source code example.
        append:
          type: boolean
          default: false
          description: If set to true, this example will be appended to the previous example.