DataProducts

Data Product Definitions must conform to the following set of rules:

Definition specification format

Each definition must be described in corresponding JSON file, which is an OpenAPI 3.x spec. Name of this file must be in UpperCamelCase.

OpenAPI schema

Rules below are applied for each definition.

Spec file must define only one POST endpoint

❌ Wrong: Two endpoints defined

{
  "paths": {
    "/AirQuality/Current": { "post": {} },
    "/Company/BasicInfo": {}
  }
}

❌ Wrong: Endpoint has POST and GET method

{
  "paths": {
    "/AirQuality/Current": { "post": {}, "get": {} }
  }
}

✅ Correct

{
  "paths": {
    "/AirQuality/Current": { "post": {} }
  }
}

Spec file must include title, description and summary fields

Main file must have a title and description and POST definition must contain summary and description fields.

✅ Correct

{
  "info": {
    "title": "Current air quality",
    "description": "Current air quality (AQI) in a given location"
  },
  "paths": {
    "/AirQuality/Current": {
      "post": {
        "summary": "Current air quality",
        "description": "Current air quality (AQI) in a given location"
      }
    }
  }
}

Spec file must include request body schema

✅ Correct

{
  "paths": {
    "/AirQuality/Current": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CurrentAirQualityRequest"
              }
            }
          },
          "required": true
        },
        "components": {
          "schemas": {
            "CurrentAirQualityRequest": {}
          }
        }
      }
    }
  }
}

Spec file must include schema for successful (200 OK) response

❌ Wrong: Responses section is empty

{
  "paths": {
    "/AirQuality/Current": {
      "post": {
        "responses": {}
      }
    }
  }
}

❌ Wrong: CurrentAirQualityResponse reference is missing

{
  "paths": {
    "/AirQuality/Current": {
      "post": {
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CurrentAirQualityResponse"
                }
              }
            }
          }
        }
      },
      "components": {
        "schemas": {
          "CompanyBasicInfoRequest": {}
        }
      }
    }
  }
}

✅ Correct

{
  "paths": {
    "/AirQuality/Current": {
      "post": {
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CurrentAirQualityResponse"
                }
              }
            }
          }
        }
      },
      "components": {
        "schemas": {
          "CurrentAirQualityResponse": {}
        }
      }
    }
  }
}

Schemas for request body and responses must be of application/json content type

❌ Wrong: Schema is by mistake defined for multipart/form-data content type

{
  "paths": {
    "/AirQuality/Current": {
      "post": {
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/CurrentAirQualityRequest"
              }
            }
          },
          "required": true
        }
      }
    }
  }
}

✅ Correct

{
  "paths": {
    "/AirQuality/Current": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CurrentAirQualityRequest"
              }
            }
          },
          "required": true
        }
      }
    }
  }
}

Spec file must not define any severs

❌ Wrong: Server URLs provided

{
  "servers": [{ "url": "https://example.com" }]
}

Spec file must not define security section for API endpoint

❌ Wrong: Security section is defined for path

{
  "paths": {
    "/AirQuality/Current": {
      "post": {
        "security": {
          "ApiKeyAuth": []
        }
      }
    }
  }
}

All information should be described in American English

❌ Wrong: Definition name is in Finnish

{
  "paths": {
    "/Grafiikka/Väri": { "post": {} }
  }
}

❌ Wrong: Definition name is in British English

{
  "paths": {
    "/Graphics/Colour": { "post": {} }
  }
}

✅ Correct: Definition name is in American English

{
  "paths": {
    "/Graphics/Color": { "post": {} }
  }
}

Note: Same rule applies to all description fields.

Spec file should list all the mandatory error responses

The following responses are required and must be defined:

• 401, 403, 404, 422, 444, 500, 502, 503, 504, 550

An example of a spec with all the error codes can be found in the definition tooling repo.