publiccode-validator-api/publiccode-validator-api.oas.yaml at main · italia/publiccode-validator-api · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
openapi: 3.1.0
info:
  title: publiccode-validator-api
  version: dev
  description: >
    REST API to validate and normalize publiccode.yml files
    against the official standard.


    The `/validate` endpoint accepts both `POST` and the `QUERY`
    HTTP method (RFC 9110) with a publiccode.yml body and returns
    validation results plus a normalized version of the file.
  license:
    name: AGPL-3.0
    identifier: AGPL-3.0-only
  contact:
    url: "https://github.com/italia/publiccode-validator-api"

servers:
  - url: /v1

paths:
  /status:
    get:
      operationId: getStatus
      summary: Get API status
      tags: [status]
      responses:
        "200":
          description: OK
          headers:
            Cache-Control:
              schema:
                type: string
              example: no-cache
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Status"
              example:
                v: "1.0.0"
                commit: "abc1234"

  /validate:
    post:
      operationId: validatePubliccode
      summary: Validate a publiccode.yml file
      description: >
        Parses and validates the publiccode.yml file in the request body.
        Returns whether the file is valid, a list of validation issues,
        and a normalized version of the file if valid.


        The same endpoint also accepts the `QUERY` HTTP method.
      tags: [validation]
      parameters:
        - name: external-checks
          in: query
          required: false
          description: >
            Enable external checks such as URL reachability.
            Disabled by default for performance.
          schema:
            type: boolean
            default: false
      requestBody:
        required: true
        content:
          application/yaml:
            schema:
              type: string
            example: |
              publiccodeYmlVersion: "0.3"
              name: My Software
              url: "https://example.com/repo"
      responses:
        "200":
          description: Validation result (regardless of whether the file is valid)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationResponse"
              examples:
                valid:
                  summary: Valid file
                  value:
                    valid: true
                    results: []
                    normalized: "publiccodeYmlVersion: \"0.3\"\nname: My Software\n"
                invalid:
                  summary: Invalid file
                  value:
                    valid: false
                    results:
                      - key: publiccodeYmlVersion
                        description: "missing required field"
                    normalized: null
        "400":
          description: Bad request (e.g. empty body)
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemJSON"
              example:
                title: empty body
                detail: need a body to validate
                status: 400
        "404":
          description: Not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemJSON"
              example:
                title: Not Found
                detail: Not Found
                status: 404

components:
  schemas:
    Status:
      type: object
      required: [v, commit]
      properties:
        v:
          type: string
          description: API version
          example: "1.0.0"
        commit:
          type: string
          description: Git commit hash
          example: "abc1234"

    ValidationResponse:
      type: object
      required: [valid, results]
      properties:
        valid:
          type: boolean
          description: Whether the file passed validation with no errors
        results:
          type: array
          description: List of validation issues (warnings and errors)
          items:
            type: object
            description: A validation issue
            additionalProperties: true
        normalized:
          description: >
            Normalized publiccode.yml content, present only when
            the file is valid.
          oneOf:
            - type: string
            - type: "null"

    ProblemJSON:
      description: Error response following RFC 9457 (Problem Details for HTTP APIs)
      type: object
      required: [title, status]
      properties:
        code:
          type: string
          description: Machine-readable error code
        title:
          type: string
          description: Short human-readable summary
        detail:
          type: string
          description: Human-readable explanation
        status:
          type: integer
          description: HTTP status code