Clang API notes schema definition

README.md

API Notes Schema

Use this schema to validate Clang .apinotes files.

This JSON schema was developed using

• LLVM project source APINotesYAMLCompiler.cpp
• API Notes Documentation

The following rules were extracted from the CPP source:

• Required properties (such as Name)
• Enums for definitions of properties such SwiftWrapperKind (none, struct or enum)
• Mutual exclusion such as for Tags where you must use EnumKind or EnumExtensibility / FlagEnum

Certain IDEs (IntelliJ) will report schema violations on the fly and will provide auto-completion of schema properties.

apinotes.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "http://github.com/stuartcarnie/swift/apinotes.json",
  "title": "clang API Notes schema",
  "description": "https://github.com/apple/llvm-project/blob/apple/master/clang/docs/APINotes.rst",
  "type": "object",
  "required": ["Name"],
  "allOf": [
    {"$ref": "#topLevelItems"},
    {
      "additionalProperties": false,
      "properties": {
        "Name": {
          "description": "The name of the module (the framework name, for frameworks)",
          "type": "string"
        },
        "Availability": {
          "$ref": "#/definitions/APIAvailabilityKind"
        },
        "SwiftInferImportAsMember": {
          "type": "boolean",
          "default": true
        },
        "SwiftVersions": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/Versioned"
          }
        }
      }
    }
  ],
  "definitions": {
    "topLevelItems": {
      "$id": "#topLevelItems",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "Classes": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/Class"
          }
        },
        "Protocols": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/Class"
          }
        },
        "Functions": {
          "description": "A list of functions to refine",
          "type": "array",
          "items": {
            "$ref": "#/definitions/Function"
          }
        },
        "Globals": {
          "description": "A list of global variables to refine",
          "type": "array",
          "items": {
            "$ref": "#/definitions/GlobalVariable"
          }
        },
        "Enumerators": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/EnumConstant"
          }
        },
        "Tags": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/Tag"
          }
        },
        "Typedefs": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/TypeDef"
          }
        }
      }
    },
    "NullabilityKind": {
      "type": "string",
      "description": "N (Not Optional), O (Optional), U (Unspecified), S (Unspecified)\nNote that 'Nullability' is overridden by 'Type', even in a \"SwiftVersions\" section.",
      "enum": ["N", "O", "U", "S"],
      "default": "N"
    },
    "NullabilitySetOrStringKind": {
      "oneOf": [
        {"type": "string", "$ref": "#/definitions/NullabilityKind"},
        {"type": "array", "items": {"$ref": "#/definitions/NullabilityKind"}}
      ]
    },
    "FactoryAsInitKind": {
      "type": "string",
      "enum": ["A", "C", "I"],
      "description": "A (infer), C (as class method), I (as initializer)"
    },
    "MethodKind": {
      "type": "string",
      "enum": ["Class", "Instance"]
    },
    "APIAvailabilityKind": {
      "type": "string",
      "enum": ["OSX", "iOS", "none", "nonswift", "available"],
      "description": "A value of \"nonswift\" is equivalent to NS_SWIFT_UNAVAILABLE. A value of \"available\" can be used in the \"SwiftVersions\" section to undo the effect of \"nonswift\"."
    },
    "SwiftWrapperKind": {
      "type": "string",
      "enum": ["none", "struct", "enum"]
    },
    "EnumExtensibilityKind": {
      "type": "string",
      "enum": ["none", "open", "closed"]
    },
    "EnumConvenienceAliasKind": {
      "type": "string",
      "enum": ["none", "CFEnum", "NSEnum", "CFOptions", "NSOptions", "CFClosedEnum", "NSClosedEnum"]
    },
    "RetainCountConventionKind": {
      "type": "string",
      "enum": ["none", "CFReturnsRetained", "CFReturnsNotRetained", "NSReturnsRetained", "NSReturnsNotRetained"]
    },
    "SwiftNameKind": {
      "type": "string",
      "description": "Equivalent to NS_SWIFT_NAME. For a method, must include the full Swift name with all arguments. Use \"_\" to omit an argument label.",
      "examples": [
        "present(_:animated:)"
      ]
    },
    "TypeKind": {
      "type": "string",
      "description": "This completely overrides the type for the specified element; it should ideally only be used for Swift backwards compatibility, when existing type information has been made more precise in a header.\n\nNote that the type is not parsed in the context where it will be used, which means that macros are not available and nullability must be applied explicitly (even in an NS_ASSUME_NONNULL_BEGIN section)."
    },
    "Param": {
      "type": "object",
      "required": ["Position"],
      "additionalProperties": false,
      "properties": {
        "Position": {
          "type": "integer",
          "minimum": 0
        },
        "Nullability": {
          "$ref": "#/definitions/NullabilityKind"
        },
        "RetainCountConvention": {
          "type": "string",
          "$ref": "#/definitions/RetainCountConventionKind"
        },
        "NoEscape": {
          "type": "boolean"
        },
        "Type": {
          "$ref": "#/definitions/TypeKind",
          "examples": ["NSArray * _Nonnull"]
        }
      }
    },
    "Property": {
      "type": "object",
      "required": ["Name"],
      "additionalProperties": false,
      "properties": {
        "Name": {
          "type": "string"
        },
        "PropertyKind": {
          "type": "string",
          "$ref": "#/definitions/MethodKind"
        },
        "Nullability": {
          "type": "string",
          "$ref": "#/definitions/NullabilityKind"
        },
        "Availability": {
          "$ref": "#/definitions/APIAvailabilityKind"
        },
        "SwiftPrivate": {
          "type": "boolean",
          "description": "Equivalent to NS_REFINED_FOR_SWIFT."
        },
        "SwiftName": {
          "$ref": "#/definitions/SwiftNameKind"
        },
        "SwiftImportAsAccessors": {
          "type": "boolean",
          "description": "If true, the property will be exposed in Swift as its accessor methods, rather than as a computed property using var."
        },
        "Type": {
          "$ref": "#/definitions/TypeKind",
          "examples": ["NSArray * _Nonnull"]
        }
      }
    },
    "Method": {
      "type": "object",
      "required": ["Selector", "MethodKind"],
      "additionalProperties": false,
      "properties": {
        "Selector": {
          "type": "string"
        },
        "MethodKind": {
          "type": "string",
          "$ref": "#/definitions/MethodKind"
        },
        "Parameters": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/Param"
          }
        },
        "Nullability": {
          "$ref": "#/definitions/NullabilitySetOrStringKind"
        },
        "NullabilityOfRet": {
          "$ref": "#/definitions/NullabilityKind"
        },
        "RetainCountConvention": {
          "$ref": "#/definitions/RetainCountConventionKind"
        },
        "Availability": {
          "$ref": "#/definitions/APIAvailabilityKind"
        },
        "AvailabilityMsg": {
          "type": "string"
        },
        "SwiftPrivate": {
          "type": "boolean",
          "description": "Equivalent to NS_REFINED_FOR_SWIFT."
        },
        "SwiftName": {
          "$ref": "#/definitions/SwiftNameKind"
        },
        "FactoryAsInit": {
          "type": "string",
          "$ref": "#/definitions/FactoryAsInitKind",
          "default": "A"
        },
        "DesignatedInit": {
          "type": "boolean",
          "default": false
        },
        "Required": {
          "type": "boolean",
          "default": false
        },
        "ResultType": {
          "$ref": "#/definitions/TypeKind",
          "examples": ["NSArray * _Nonnull"],
          "default": ""
        }
      }
    },
    "Class": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "Name": {
          "type": "string"
        },
        "AuditedForNullability": {
          "type": "boolean",
          "default": false
        },
        "Availability": {
          "$ref": "#/definitions/APIAvailabilityKind"
        },
        "AvailabilityMsg": {
          "type": "string"
        },
        "SwiftPrivate": {
          "type": "boolean",
          "description": "Equivalent to NS_REFINED_FOR_SWIFT."
        },
        "SwiftName": {
          "type": "string",
          "$ref": "#/definitions/SwiftNameKind"
        },
        "SwiftBridge": {
          "type": "string",
          "$comment": "Used for Objective-C class types bridged to Swift value types. No support outside Apple frameworks"
        },
        "NSErrorDomain": {
          "type": "string",
          "$comment": "Used for NSError code enums. The value is the name of the associated domain NSString constant."
        },
        "SwiftImportAsNonGeneric": {
          "type": "boolean"
        },
        "SwiftObjCMembers": {
          "type": "boolean"
        },
        "Methods": {
          "type": "array",
          "$ref": "#/definitions/Method"
        },
        "Properties": {
          "type": "array",
          "$ref": "#/definitions/Property"
        }
      }
    },
    "Function": {
      "type": "object",
      "required": ["Name"],
      "additionalProperties": false,
      "properties": {
        "Name": {
          "type": "string"
        },
        "Parameters": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/Param"
          }
        },
        "Nullability": {
          "$ref": "#/definitions/NullabilitySetOrStringKind"
        },
        "NullabilityOfRet": {
          "$ref": "#/definitions/NullabilityKind"
        },
        "RetainCountConvention": {
          "$ref": "#/definitions/RetainCountConventionKind"
        },
        "Availability": {
          "$ref": "#/definitions/APIAvailabilityKind"
        },
        "AvailabilityMsg": {
          "type": "string"
        },
        "SwiftPrivate": {
          "type": "boolean",
          "description": "Equivalent to NS_REFINED_FOR_SWIFT."
        },
        "SwiftName": {
          "$ref": "#/definitions/SwiftNameKind"
        },
        "ResultType": {
          "$ref": "#/definitions/TypeKind",
          "examples": ["NSArray * _Nonnull"],
          "default": ""
        }
      }
    },
    "GlobalVariable": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "Name": {
          "type": "string"
        },
        "Nullability": {
          "$ref": "#/definitions/NullabilityKind"
        },
        "Availability": {
          "$ref": "#/definitions/APIAvailabilityKind"
        },
        "AvailabilityMsg": {
          "type": "string"
        },
        "SwiftPrivate": {
          "type": "boolean",
          "description": "Equivalent to NS_REFINED_FOR_SWIFT."
        },
        "SwiftName": {
          "type": "string",
          "$ref": "#/definitions/SwiftNameKind"
        },
        "Type": {
          "$ref": "#/definitions/TypeKind",
          "examples": ["NSArray * _Nonnull"]
        }
      }
    },
    "EnumConstant": {
      "type": "object",
      "required": ["Name"],
      "properties": {
        "Name": {
          "type": "string"
        },
        "Availability": {
          "$ref": "#/definitions/APIAvailabilityKind"
        },
        "AvailabilityMsg": {
          "type": "string"
        },
        "SwiftPrivate": {
          "type": "boolean",
          "description": "Equivalent to NS_REFINED_FOR_SWIFT."
        },
        "SwiftName": {
          "$ref": "#/definitions/SwiftNameKind"
        }
      }
    },
    "Tag": {
      "type": "object",
      "required": ["Name"],
      "additionalProperties": false,
      "properties": {
        "Name": {
          "type": "string"
        },
        "Availability": {
          "$ref": "#/definitions/APIAvailabilityKind"
        },
        "AvailabilityMsg": {
          "type": "string"
        },
        "SwiftPrivate": {
          "type": "boolean",
          "description": "Equivalent to NS_REFINED_FOR_SWIFT."
        },
        "SwiftName": {
          "$ref": "#/definitions/SwiftNameKind"
        },
        "SwiftBridge": {
          "type": "string",
          "$comment": "Used for Objective-C class types bridged to Swift value types. No support outside Apple frameworks"
        },
        "NSErrorDomain": {
          "type": "string",
          "$comment": "Used for NSError code enums. The value is the name of the associated domain NSString constant."
        }
      },
      "oneOf": [
        {
          "required": ["EnumKind"],
          "additionalProperties": false,
          "properties": {
            "EnumKind": {
              "type": "string",
              "$ref": "#/definitions/EnumConvenienceAliasKind"
            }
          }
        },
        {
          "additionalProperties": false,
          "properties": {
            "EnumExtensibility": {
              "type": "string",
              "$ref": "#/definitions/EnumExtensibilityKind"
            },
            "FlagEnum": {
              "type": "boolean"
            }
          }
        }
      ]
    },
    "TypeDef": {
      "type": "object",
      "required": ["Name"],
      "additionalProperties": false,
      "properties": {
        "Name": {
          "type": "string"
        },
        "Availability": {
          "$ref": "#/definitions/APIAvailabilityKind"
        },
        "AvailabilityMsg": {
          "type": "string"
        },
        "SwiftPrivate": {
          "type": "boolean",
          "description": "Equivalent to NS_REFINED_FOR_SWIFT."
        },
        "SwiftName": {
          "$ref": "#/definitions/SwiftNameKind"
        },
        "SwiftBridge": {
          "type": "string",
          "$comment": "Used for Objective-C class types bridged to Swift value types. No support outside Apple frameworks"
        },
        "NSErrorDomain": {
          "type": "string",
          "$comment": "Used for NSError code enums. The value is the name of the associated domain NSString constant."
        },
        "SwiftWrapper": {
          "type": "string",
          "$ref": "#/definitions/SwiftWrapperKind"
        }
      }
    },
    "Versioned": {
      "type": "object",
      "additionalProperties": false,
      "required": ["Version"],
      "allOf": [
        {
          "additionalProperties": false,
          "properties": {
            "Version": {
              "description": "Contains explicit information for backwards compatibility",
              "type": "string",
              "pattern": "^(\\d)(\\.\\d){0,2}$"
            }
          }
        },
        {"$ref": "#topLevelItems"}
      ]
    }
  }
}

LICENSE.txt

   Copyright 2020 Stuart Carnie

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.