From 8ab66746c899379c4cc591263e205fb140988539 Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Tue, 7 Feb 2023 17:16:31 -0500
Subject: [PATCH 1/5] Add yaml spec.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 plugins/catalog-backend/openapi.yaml | 755 +++++++++++++++++++++++++++
 1 file changed, 755 insertions(+)
 create mode 100644 plugins/catalog-backend/openapi.yaml

diff --git a/plugins/catalog-backend/openapi.yaml b/plugins/catalog-backend/openapi.yaml
new file mode 100644
index 0000000000..a058831d55
--- /dev/null
+++ b/plugins/catalog-backend/openapi.yaml
@@ -0,0 +1,755 @@
+components:
+  examples: {}
+  headers: {}
+  parameters: {}
+  requestBodies: {}
+  responses: {}
+  schemas:
+    RefreshOptions:
+      properties:
+        authorizationToken:
+          type: string
+        entityRef:
+          type: string
+          description: The reference to a single entity that should be refreshed
+      required:
+        - entityRef
+      type: object
+      description: Options for requesting a refresh of entities in the catalog.
+    JsonObject:
+      properties: {}
+      type: object
+      description: A type representing all allowed JSON object values.
+    MapStringString:
+      properties: {}
+      type: object
+      additionalProperties:
+        type: string
+      description: Construct a type with a set of properties K of type T
+    EntityLink:
+      properties:
+        type:
+          type: string
+          description: An optional value to categorize links into specific groups
+        icon:
+          type: string
+          description: An optional semantic key that represents a visual icon.
+        title:
+          type: string
+          description: An optional descriptive title for the link.
+        url:
+          type: string
+          description: The url to the external site, document, etc.
+      required:
+        - url
+      type: object
+      description: A link to external information that is related to the entity.
+    EntityMeta:
+      allOf:
+        - $ref: '#/components/schemas/JsonObject'
+        - properties:
+            links:
+              items:
+                $ref: '#/components/schemas/EntityLink'
+              type: array
+              description: A list of external hyperlinks related to the entity.
+            tags:
+              items:
+                type: string
+              type: array
+              description: |-
+                A list of single-valued strings, to for example classify catalog entities in
+                various ways.
+            annotations:
+              $ref: '#/components/schemas/MapStringString'
+            labels:
+              $ref: '#/components/schemas/MapStringString'
+            description:
+              type: string
+              description: |-
+                A short (typically relatively few words, on one line) description of the
+                entity.
+            title:
+              type: string
+              description: |-
+                A display name of the entity, to be presented in user interfaces instead
+                of the `name` property above, when available.
+                This field is sometimes useful when the `name` is cumbersome or ends up
+                being perceived as overly technical. The title generally does not have
+                as stringent format requirements on it, so it may contain special
+                characters and be more explanatory. Do keep it very short though, and
+                avoid situations where a title can be confused with the name of another
+                entity, or where two entities share a title.
+                Note that this is only for display purposes, and may be ignored by some
+                parts of the code. Entity references still always make use of the `name`
+                property, not the title.
+            namespace:
+              type: string
+              description: The namespace that the entity belongs to.
+            name:
+              type: string
+              description: |-
+                The name of the entity.
+                Must be unique within the catalog at any given point in time, for any
+                given namespace + kind pair. This value is part of the technical
+                identifier of the entity, and as such it will appear in URLs, database
+                tables, entity references, and similar. It is subject to restrictions
+                regarding what characters are allowed.
+                If you want to use a different, more human readable string with fewer
+                restrictions on it in user interfaces, see the `title` field below.
+            etag:
+              type: string
+              description: |-
+                An opaque string that changes for each update operation to any part of
+                the entity, including metadata.
+                This field can not be set by the user at creation time, and the server
+                will reject an attempt to do so. The field will be populated in read
+                operations. The field can (optionally) be specified when performing
+                update or delete operations, and the server will then reject the
+                operation if it does not match the current stored value.
+            uid:
+              type: string
+              description: |-
+                A globally unique ID for the entity.
+                This field can not be set by the user at creation time, and the server
+                will reject an attempt to do so. The field will be populated in read
+                operations. The field can (optionally) be specified when performing
+                update or delete operations, but the server is free to reject requests
+                that do so in such a way that it breaks semantics.
+          required:
+            - name
+          type: object
+      description: Metadata fields common to all versions/kinds of entity.
+    EntityRelation:
+      properties:
+        targetRef:
+          type: string
+          description: The entity ref of the target of this relation.
+        type:
+          type: string
+          description: The type of the relation.
+      required:
+        - targetRef
+        - type
+      type: object
+      description: A relation of a specific type to another entity in the catalog.
+    Entity:
+      properties:
+        relations:
+          items:
+            $ref: '#/components/schemas/EntityRelation'
+          type: array
+          description: The relations that this entity has with other entities.
+        spec:
+          $ref: '#/components/schemas/JsonObject'
+        metadata:
+          $ref: '#/components/schemas/EntityMeta'
+        kind:
+          type: string
+          description: The high level entity type being described.
+        apiVersion:
+          type: string
+          description: |-
+            The version of specification format for this particular entity that
+            this is written against.
+      required:
+        - metadata
+        - kind
+        - apiVersion
+      type: object
+      description: The parts of the format that's common to all versions/kinds of entity.
+    EntityAncestryResponse:
+      properties:
+        items:
+          items:
+            properties:
+              parentEntityRefs:
+                items:
+                  type: string
+                type: array
+              entity:
+                $ref: '#/components/schemas/Entity'
+            required:
+              - parentEntityRefs
+              - entity
+            type: object
+          type: array
+        rootEntityRef:
+          type: string
+      required:
+        - items
+        - rootEntityRef
+      type: object
+    EntitiesBatchResponse:
+      properties:
+        items:
+          items:
+            allOf:
+              - $ref: '#/components/schemas/Entity'
+            nullable: true
+          type: array
+          description: |-
+            The list of entities, in the same order as the refs in the request. Entries
+            that are null signify that no entity existed with that ref.
+      required:
+        - items
+      type: object
+    EntityFacets:
+      type: object
+      properties: 
+        value: 
+          type: string
+        count: 
+          type: number
+      description: Construct a type with a set of properties K of type T
+    EntityFacetsResponse:
+      properties: {}
+      type: object
+      additionalProperties:
+          $ref: '#/components/schemas/EntityFacets'
+      required:
+        - facets
+    Location:
+      properties:
+        target:
+          type: string
+        type:
+          type: string
+        id:
+          type: string
+      required:
+        - target
+        - type
+        - id
+      type: object
+      description: Entity location for a specific entity.
+    LocationSpec:
+      properties:
+        presence:
+          type: string
+          enum:
+            - optional
+            - required
+        target:
+          type: string
+        type:
+          type: string
+      required:
+        - target
+        - type
+      type: object
+      description: Holds the entity location information.
+    AnalyzeLocationExistingEntity:
+      properties:
+        entity:
+          $ref: '#/components/schemas/Entity'
+        isRegistered:
+          type: boolean
+        location:
+          $ref: '#/components/schemas/LocationSpec'
+      required:
+        - entity
+        - isRegistered
+        - location
+      type: object
+      description: |-
+        If the folder pointed to already contained catalog info yaml files, they are
+        read and emitted like this so that the frontend can inform the user that it
+        located them and can make sure to register them as well if they weren't
+        already
+    RecursivePartial_Entity_:
+      properties:
+        apiVersion:
+          type: string
+          description: |-
+            The version of specification format for this particular entity that
+            this is written against.
+        kind:
+          type: string
+          description: The high level entity type being described.
+        metadata:
+          $ref: '#/components/schemas/EntityMeta'
+        spec:
+          $ref: '#/components/schemas/JsonObject'
+        relations:
+          items:
+            $ref: '#/components/schemas/EntityRelation'
+          type: array
+          description: The relations that this entity has with other entities.
+      type: object
+      description: Makes all keys of an entire hierarchy optional.
+    AnalyzeLocationEntityField:
+      properties:
+        description:
+          type: string
+          description: |-
+            A text to show to the user to inform about the choices made. Like, it could say
+            "Found a CODEOWNERS file that covers this target, so we suggest leaving this
+            field empty; which would currently make it owned by X" where X is taken from the
+            codeowners file.
+        value:
+          type: string
+          nullable: true
+        state:
+          type: string
+          enum:
+            - analysisSuggestedValue
+            - analysisSuggestedNoValue
+            - needsUserInput
+          description: The outcome of the analysis for this particular field
+        field:
+          type: string
+          description: |-
+            e.g. "spec.owner"? The frontend needs to know how to "inject" the field into the
+            entity again if the user wants to change it
+      required:
+        - description
+        - value
+        - state
+        - field
+      type: object
+    AnalyzeLocationGenerateEntity:
+      properties:
+        fields:
+          items:
+            $ref: '#/components/schemas/AnalyzeLocationEntityField'
+          type: array
+        entity:
+          $ref: '#/components/schemas/RecursivePartial_Entity_'
+      required:
+        - fields
+        - entity
+      type: object
+      description: |-
+        This is some form of representation of what the analyzer could deduce.
+        We should probably have a chat about how this can best be conveyed to
+        the frontend. It'll probably contain a (possibly incomplete) entity, plus
+        enough info for the frontend to know what form data to show to the user
+        for overriding/completing the info.
+    AnalyzeLocationResponse:
+      properties:
+        generateEntities:
+          items:
+            $ref: '#/components/schemas/AnalyzeLocationGenerateEntity'
+          type: array
+        existingEntityFiles:
+          items:
+            $ref: '#/components/schemas/AnalyzeLocationExistingEntity'
+          type: array
+      required:
+        - generateEntities
+        - existingEntityFiles
+      type: object
+    LocationInput:
+      properties:
+        type:
+          type: string
+        target:
+          type: string
+        presence:
+          type: string
+          enum:
+            - optional
+            - required
+      required:
+        - type
+        - target
+        - presence
+      type: object
+    SerializedError:
+      allOf:
+        - $ref: '#/components/schemas/JsonObject'
+        - properties:
+            code:
+              type: string
+              description: A custom code (not necessarily the same as an HTTP response code); may not be present
+            stack:
+              type: string
+              description: A stringified stack trace; may not be present
+            message:
+              type: string
+              description: The message of the exception that was thrown
+            name:
+              type: string
+              description: The name of the exception that was thrown
+          required:
+            - message
+            - name
+          type: object
+      description: The serialized form of an Error.
+  securitySchemes:
+    JWT:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+info:
+  title: '@backstage/plugin-catalog-backend'
+  version: 1.6.0-next.1
+  description: The Backstage backend plugin that provides the Backstage catalog
+  license:
+    name: Apache-2.0
+  contact: {}
+openapi: 3.0.3
+paths:
+  /refresh:
+    post:
+      operationId: RefreshEntity
+      responses:
+        '200':
+          description: Refreshed
+      security:
+        - JWT: []
+      parameters: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RefreshOptions'
+  /entities:
+    get:
+      operationId: GetEntities
+      responses:
+        '200':
+          description: ''
+          content:
+            application/json:
+              schema:
+                items:
+                  $ref: '#/components/schemas/Entity'
+                type: array
+      security:
+        - JWT: []
+      parameters:
+        - in: query
+          name: filter
+          required: false
+          schema:
+            type: string
+        - in: query
+          name: fields
+          required: false
+          schema:
+            type: string
+        - in: query
+          name: offset
+          required: false
+          schema:
+            type: string
+        - in: query
+          name: limit
+          required: false
+          schema:
+            type: string
+        - in: query
+          name: after
+          required: false
+          schema:
+            type: string
+  /entities/by-uid/{uid}:
+    get:
+      operationId: GetEntityByUid
+      responses:
+        '200':
+          description: Ok
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Entity'
+      security:
+        - JWT: []
+      parameters:
+        - in: path
+          name: uid
+          required: true
+          schema:
+            type: string
+    delete:
+      operationId: DeleteEntityByUid
+      responses:
+        '204':
+          description: Deleted successfully.
+      security:
+        - JWT: []
+      parameters:
+        - in: path
+          name: uid
+          required: true
+          schema:
+            type: string
+
+  /entities/by-name/{kind}/{namespace}/{name}:
+    get:
+      operationId: GetEntityByName
+      responses:
+        '200':
+          description: Ok
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Entity'
+      security:
+        - JWT: []
+      parameters:
+        - in: path
+          name: kind
+          required: true
+          schema:
+            type: string
+        - in: path
+          name: namespace
+          required: true
+          schema:
+            type: string
+        - in: path
+          name: name
+          required: true
+          schema:
+            type: string
+  /entities/by-name/{kind}/{namespace}/{name}/ancestry:
+    get:
+      operationId: GetEntityAncestryByName
+      responses:
+        '200':
+          description: Ok
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/EntityAncestryResponse'
+      security:
+        - JWT: []
+      parameters:
+        - in: path
+          name: kind
+          required: true
+          schema:
+            type: string
+        - in: path
+          name: namespace
+          required: true
+          schema:
+            type: string
+        - in: path
+          name: name
+          required: true
+          schema:
+            type: string
+  /entities/by-refs:
+    post:
+      operationId: GetEntitiesByRefs
+      responses:
+        '200':
+          description: Ok
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/EntitiesBatchResponse'
+      security:
+        - JWT: []
+      parameters:
+        - in: query
+          name: fields
+          required: false
+          schema:
+            type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              items:
+                type: string
+              type: array
+  /entity-facets:
+    get:
+      operationId: GetEntityFacets
+      responses:
+        '200':
+          description: Ok
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/EntityFacetsResponse'
+      security:
+        - JWT: []
+      parameters:
+        - in: query
+          name: facet
+          required: true
+          schema:
+            type: string
+        - in: query
+          name: filter
+          required: false
+          schema:
+            type: string
+  /locations:
+    post:
+      operationId: CreateLocation
+      responses:
+        '200':
+          description: Ok
+          content:
+            application/json:
+              schema:
+                properties:
+                  exists:
+                    type: boolean
+                  entities:
+                    items:
+                      $ref: '#/components/schemas/Entity'
+                    type: array
+                  location:
+                    $ref: '#/components/schemas/Location'
+                required:
+                  - entities
+                  - location
+                type: object
+      security:
+        - JWT: []
+      parameters:
+        - in: query
+          name: dryRun
+          required: false
+          schema:
+            type: boolean
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              properties:
+                presence:
+                  type: string
+                  enum:
+                    - required
+                    - optional
+                target:
+                  type: string
+                type:
+                  type: string
+              required:
+                - presence
+                - target
+                - type
+              type: object
+    get:
+      operationId: GetLocations
+      responses:
+        '200':
+          description: Ok
+          content:
+            application/json:
+              schema:
+                items:
+                  properties:
+                    data:
+                      $ref: '#/components/schemas/Location'
+                  required:
+                    - data
+                  type: object
+                type: array
+      security:
+        - JWT: []
+      parameters: []
+  /locations/{id}:
+    get:
+      operationId: GetLocation
+      responses:
+        '200':
+          description: Ok
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Location'
+      security:
+        - JWT: []
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema:
+            type: string
+    delete:
+      operationId: DeleteLocation
+      responses:
+        '204':
+          description: No content
+      security:
+        - JWT: []
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema:
+            type: string
+  /analyze-location:
+    post:
+      operationId: AnalyzeLocation
+      responses:
+        '200':
+          description: Ok
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AnalyzeLocationResponse'
+      security:
+        - JWT: []
+      parameters: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              properties:
+                catalogFileName:
+                  type: string
+                location:
+                  $ref: '#/components/schemas/LocationInput'
+              required:
+                - catalogFileName
+                - location
+              type: object
+  /validate-entity:
+    post:
+      operationId: ValidateEntity
+      responses:
+        '200':
+          description: Ok
+          content:
+            application/json:
+              schema:
+                anyOf:
+                  - properties:
+                      errors:
+                        $ref: '#/components/schemas/SerializedError'
+                    required:
+                      - errors
+                    type: object
+                  - properties:
+                      errors:
+                        items:
+                          $ref: '#/components/schemas/SerializedError'
+                        type: array
+                    required:
+                      - errors
+                    type: object
+      security:
+        - JWT: []
+      parameters: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              properties:
+                location:
+                  type: string
+                entity:
+                  $ref: '#/components/schemas/Entity'
+              required:
+                - location
+                - entity
+              type: object
+servers:
+  - url: /

From 3951fa0b31a09d20d959768450c0bc1e3bf1e00f Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Tue, 7 Feb 2023 17:37:56 -0500
Subject: [PATCH 2/5] Use 3.1

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 plugins/catalog-backend/openapi.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/plugins/catalog-backend/openapi.yaml b/plugins/catalog-backend/openapi.yaml
index a058831d55..fdd1532f89 100644
--- a/plugins/catalog-backend/openapi.yaml
+++ b/plugins/catalog-backend/openapi.yaml
@@ -389,7 +389,7 @@ info:
   license:
     name: Apache-2.0
   contact: {}
-openapi: 3.0.3
+openapi: 3.1.0
 paths:
   /refresh:
     post:

From 1fd29bffc72cf4984af87af5e3a8406226c7f8ac Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Tue, 7 Feb 2023 17:42:40 -0500
Subject: [PATCH 3/5] Formatting and make security optional

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 plugins/catalog-backend/openapi.yaml | 31 +++++++++++++++++++++-------
 1 file changed, 23 insertions(+), 8 deletions(-)

diff --git a/plugins/catalog-backend/openapi.yaml b/plugins/catalog-backend/openapi.yaml
index fdd1532f89..beef95b0b7 100644
--- a/plugins/catalog-backend/openapi.yaml
+++ b/plugins/catalog-backend/openapi.yaml
@@ -1,3 +1,11 @@
+openapi: 3.1.0
+info:
+  title: '@backstage/plugin-catalog-backend'
+  version: '1'
+  description: The Backstage backend plugin that provides the Backstage catalog
+  license:
+    name: Apache-2.0
+  contact: {}
 components:
   examples: {}
   headers: {}
@@ -382,14 +390,7 @@ components:
       type: http
       scheme: bearer
       bearerFormat: JWT
-info:
-  title: '@backstage/plugin-catalog-backend'
-  version: 1.6.0-next.1
-  description: The Backstage backend plugin that provides the Backstage catalog
-  license:
-    name: Apache-2.0
-  contact: {}
-openapi: 3.1.0
+
 paths:
   /refresh:
     post:
@@ -398,6 +399,7 @@ paths:
         '200':
           description: Refreshed
       security:
+        - {}
         - JWT: []
       parameters: []
       requestBody:
@@ -419,6 +421,7 @@ paths:
                   $ref: '#/components/schemas/Entity'
                 type: array
       security:
+        - {}
         - JWT: []
       parameters:
         - in: query
@@ -457,6 +460,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/Entity'
       security:
+        - {}
         - JWT: []
       parameters:
         - in: path
@@ -470,6 +474,7 @@ paths:
         '204':
           description: Deleted successfully.
       security:
+        - {}
         - JWT: []
       parameters:
         - in: path
@@ -489,6 +494,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/Entity'
       security:
+        - {}
         - JWT: []
       parameters:
         - in: path
@@ -517,6 +523,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/EntityAncestryResponse'
       security:
+        - {}
         - JWT: []
       parameters:
         - in: path
@@ -545,6 +552,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/EntitiesBatchResponse'
       security:
+        - {}
         - JWT: []
       parameters:
         - in: query
@@ -571,6 +579,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/EntityFacetsResponse'
       security:
+        - {}
         - JWT: []
       parameters:
         - in: query
@@ -606,6 +615,7 @@ paths:
                   - location
                 type: object
       security:
+        - {}
         - JWT: []
       parameters:
         - in: query
@@ -650,6 +660,7 @@ paths:
                   type: object
                 type: array
       security:
+        - {}
         - JWT: []
       parameters: []
   /locations/{id}:
@@ -663,6 +674,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/Location'
       security:
+        - {}
         - JWT: []
       parameters:
         - in: path
@@ -676,6 +688,7 @@ paths:
         '204':
           description: No content
       security:
+        - {}
         - JWT: []
       parameters:
         - in: path
@@ -694,6 +707,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/AnalyzeLocationResponse'
       security:
+        - {}
         - JWT: []
       parameters: []
       requestBody:
@@ -735,6 +749,7 @@ paths:
                       - errors
                     type: object
       security:
+        - {}
         - JWT: []
       parameters: []
       requestBody:

From 5cc2a75994ad92cfa3ef835a71775146bf6a9059 Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Tue, 7 Feb 2023 17:44:30 -0500
Subject: [PATCH 4/5] Add comment to yaml

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 plugins/catalog-backend/openapi.yaml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/plugins/catalog-backend/openapi.yaml b/plugins/catalog-backend/openapi.yaml
index beef95b0b7..9215f562f5 100644
--- a/plugins/catalog-backend/openapi.yaml
+++ b/plugins/catalog-backend/openapi.yaml
@@ -399,6 +399,7 @@ paths:
         '200':
           description: Refreshed
       security:
+        # From https://stackoverflow.com/questions/47659324/how-to-specify-an-endpoints-authorization-is-optional-in-openapi-v3
         - {}
         - JWT: []
       parameters: []

From 111f5d475b018411cd8e0e0a2c074917746584d3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fredrik=20Adel=C3=B6w?= <freben@gmail.com>
Date: Wed, 8 Feb 2023 09:45:30 +0100
Subject: [PATCH 5/5] prettier
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Fredrik Adelöw <freben@gmail.com>
---
 plugins/catalog-backend/openapi.yaml | 108 +++++++++++++++------------
 1 file changed, 60 insertions(+), 48 deletions(-)

diff --git a/plugins/catalog-backend/openapi.yaml b/plugins/catalog-backend/openapi.yaml
index 9215f562f5..ea09f5da10 100644
--- a/plugins/catalog-backend/openapi.yaml
+++ b/plugins/catalog-backend/openapi.yaml
@@ -1,4 +1,5 @@
 openapi: 3.1.0
+
 info:
   title: '@backstage/plugin-catalog-backend'
   version: '1'
@@ -6,6 +7,10 @@ info:
   license:
     name: Apache-2.0
   contact: {}
+
+servers:
+  - url: /
+
 components:
   examples: {}
   headers: {}
@@ -14,6 +19,7 @@ components:
   responses: {}
   schemas:
     RefreshOptions:
+      type: object
       properties:
         authorizationToken:
           type: string
@@ -22,19 +28,19 @@ components:
           description: The reference to a single entity that should be refreshed
       required:
         - entityRef
-      type: object
       description: Options for requesting a refresh of entities in the catalog.
     JsonObject:
-      properties: {}
       type: object
+      properties: {}
       description: A type representing all allowed JSON object values.
     MapStringString:
-      properties: {}
       type: object
+      properties: {}
       additionalProperties:
         type: string
       description: Construct a type with a set of properties K of type T
     EntityLink:
+      type: object
       properties:
         type:
           type: string
@@ -50,21 +56,21 @@ components:
           description: The url to the external site, document, etc.
       required:
         - url
-      type: object
       description: A link to external information that is related to the entity.
     EntityMeta:
       allOf:
         - $ref: '#/components/schemas/JsonObject'
-        - properties:
+        - type: object
+          properties:
             links:
+              type: array
               items:
                 $ref: '#/components/schemas/EntityLink'
-              type: array
               description: A list of external hyperlinks related to the entity.
             tags:
+              type: array
               items:
                 type: string
-              type: array
               description: |-
                 A list of single-valued strings, to for example classify catalog entities in
                 various ways.
@@ -126,9 +132,9 @@ components:
                 that do so in such a way that it breaks semantics.
           required:
             - name
-          type: object
       description: Metadata fields common to all versions/kinds of entity.
     EntityRelation:
+      type: object
       properties:
         targetRef:
           type: string
@@ -139,14 +145,14 @@ components:
       required:
         - targetRef
         - type
-      type: object
       description: A relation of a specific type to another entity in the catalog.
     Entity:
+      type: object
       properties:
         relations:
+          type: array
           items:
             $ref: '#/components/schemas/EntityRelation'
-          type: array
           description: The relations that this entity has with other entities.
         spec:
           $ref: '#/components/schemas/JsonObject'
@@ -164,12 +170,14 @@ components:
         - metadata
         - kind
         - apiVersion
-      type: object
       description: The parts of the format that's common to all versions/kinds of entity.
     EntityAncestryResponse:
+      type: object
       properties:
         items:
+          type: array
           items:
+            type: object
             properties:
               parentEntityRefs:
                 items:
@@ -180,44 +188,42 @@ components:
             required:
               - parentEntityRefs
               - entity
-            type: object
-          type: array
         rootEntityRef:
           type: string
       required:
         - items
         - rootEntityRef
-      type: object
     EntitiesBatchResponse:
+      type: object
       properties:
         items:
+          type: array
           items:
             allOf:
               - $ref: '#/components/schemas/Entity'
             nullable: true
-          type: array
           description: |-
             The list of entities, in the same order as the refs in the request. Entries
             that are null signify that no entity existed with that ref.
       required:
         - items
-      type: object
     EntityFacets:
       type: object
-      properties: 
-        value: 
+      properties:
+        value:
           type: string
-        count: 
+        count:
           type: number
       description: Construct a type with a set of properties K of type T
     EntityFacetsResponse:
-      properties: {}
       type: object
+      properties: {}
       additionalProperties:
-          $ref: '#/components/schemas/EntityFacets'
+        $ref: '#/components/schemas/EntityFacets'
       required:
         - facets
     Location:
+      type: object
       properties:
         target:
           type: string
@@ -229,9 +235,9 @@ components:
         - target
         - type
         - id
-      type: object
       description: Entity location for a specific entity.
     LocationSpec:
+      type: object
       properties:
         presence:
           type: string
@@ -245,9 +251,9 @@ components:
       required:
         - target
         - type
-      type: object
       description: Holds the entity location information.
     AnalyzeLocationExistingEntity:
+      type: object
       properties:
         entity:
           $ref: '#/components/schemas/Entity'
@@ -259,13 +265,13 @@ components:
         - entity
         - isRegistered
         - location
-      type: object
       description: |-
         If the folder pointed to already contained catalog info yaml files, they are
         read and emitted like this so that the frontend can inform the user that it
         located them and can make sure to register them as well if they weren't
         already
     RecursivePartial_Entity_:
+      type: object
       properties:
         apiVersion:
           type: string
@@ -280,13 +286,13 @@ components:
         spec:
           $ref: '#/components/schemas/JsonObject'
         relations:
+          type: array
           items:
             $ref: '#/components/schemas/EntityRelation'
-          type: array
           description: The relations that this entity has with other entities.
-      type: object
       description: Makes all keys of an entire hierarchy optional.
     AnalyzeLocationEntityField:
+      type: object
       properties:
         description:
           type: string
@@ -315,19 +321,18 @@ components:
         - value
         - state
         - field
-      type: object
     AnalyzeLocationGenerateEntity:
+      type: object
       properties:
         fields:
+          type: array
           items:
             $ref: '#/components/schemas/AnalyzeLocationEntityField'
-          type: array
         entity:
           $ref: '#/components/schemas/RecursivePartial_Entity_'
       required:
         - fields
         - entity
-      type: object
       description: |-
         This is some form of representation of what the analyzer could deduce.
         We should probably have a chat about how this can best be conveyed to
@@ -335,6 +340,7 @@ components:
         enough info for the frontend to know what form data to show to the user
         for overriding/completing the info.
     AnalyzeLocationResponse:
+      type: object
       properties:
         generateEntities:
           items:
@@ -347,8 +353,8 @@ components:
       required:
         - generateEntities
         - existingEntityFiles
-      type: object
     LocationInput:
+      type: object
       properties:
         type:
           type: string
@@ -363,11 +369,11 @@ components:
         - type
         - target
         - presence
-      type: object
     SerializedError:
       allOf:
         - $ref: '#/components/schemas/JsonObject'
-        - properties:
+        - type: object
+          properties:
             code:
               type: string
               description: A custom code (not necessarily the same as an HTTP response code); may not be present
@@ -383,7 +389,6 @@ components:
           required:
             - message
             - name
-          type: object
       description: The serialized form of an Error.
   securitySchemes:
     JWT:
@@ -409,6 +414,7 @@ paths:
           application/json:
             schema:
               $ref: '#/components/schemas/RefreshOptions'
+
   /entities:
     get:
       operationId: GetEntities
@@ -418,9 +424,9 @@ paths:
           content:
             application/json:
               schema:
+                type: array
                 items:
                   $ref: '#/components/schemas/Entity'
-                type: array
       security:
         - {}
         - JWT: []
@@ -450,6 +456,7 @@ paths:
           required: false
           schema:
             type: string
+
   /entities/by-uid/{uid}:
     get:
       operationId: GetEntityByUid
@@ -513,6 +520,7 @@ paths:
           required: true
           schema:
             type: string
+
   /entities/by-name/{kind}/{namespace}/{name}/ancestry:
     get:
       operationId: GetEntityAncestryByName
@@ -542,6 +550,7 @@ paths:
           required: true
           schema:
             type: string
+
   /entities/by-refs:
     post:
       operationId: GetEntitiesByRefs
@@ -566,9 +575,10 @@ paths:
         content:
           application/json:
             schema:
+              type: array
               items:
                 type: string
-              type: array
+
   /entity-facets:
     get:
       operationId: GetEntityFacets
@@ -593,6 +603,7 @@ paths:
           required: false
           schema:
             type: string
+
   /locations:
     post:
       operationId: CreateLocation
@@ -602,6 +613,7 @@ paths:
           content:
             application/json:
               schema:
+                type: object
                 properties:
                   exists:
                     type: boolean
@@ -614,7 +626,6 @@ paths:
                 required:
                   - entities
                   - location
-                type: object
       security:
         - {}
         - JWT: []
@@ -629,6 +640,7 @@ paths:
         content:
           application/json:
             schema:
+              type: object
               properties:
                 presence:
                   type: string
@@ -643,7 +655,6 @@ paths:
                 - presence
                 - target
                 - type
-              type: object
     get:
       operationId: GetLocations
       responses:
@@ -652,18 +663,19 @@ paths:
           content:
             application/json:
               schema:
+                type: array
                 items:
+                  type: object
                   properties:
                     data:
                       $ref: '#/components/schemas/Location'
                   required:
                     - data
-                  type: object
-                type: array
       security:
         - {}
         - JWT: []
       parameters: []
+
   /locations/{id}:
     get:
       operationId: GetLocation
@@ -697,6 +709,7 @@ paths:
           required: true
           schema:
             type: string
+
   /analyze-location:
     post:
       operationId: AnalyzeLocation
@@ -716,6 +729,7 @@ paths:
         content:
           application/json:
             schema:
+              type: object
               properties:
                 catalogFileName:
                   type: string
@@ -724,7 +738,7 @@ paths:
               required:
                 - catalogFileName
                 - location
-              type: object
+
   /validate-entity:
     post:
       operationId: ValidateEntity
@@ -735,20 +749,20 @@ paths:
             application/json:
               schema:
                 anyOf:
-                  - properties:
+                  - type: object
+                    properties:
                       errors:
                         $ref: '#/components/schemas/SerializedError'
                     required:
                       - errors
-                    type: object
-                  - properties:
+                  - type: object
+                    properties:
                       errors:
+                        type: array
                         items:
                           $ref: '#/components/schemas/SerializedError'
-                        type: array
                     required:
                       - errors
-                    type: object
       security:
         - {}
         - JWT: []
@@ -758,6 +772,7 @@ paths:
         content:
           application/json:
             schema:
+              type: object
               properties:
                 location:
                   type: string
@@ -766,6 +781,3 @@ paths:
               required:
                 - location
                 - entity
-              type: object
-servers:
-  - url: /