{
	"openapi": "3.0.1",
	"info": {
		"title": "Railcard Vaildation Service",
		"description": "",
		"version": "3"
	},
	"tags": [],
	"paths": {
		"/health": {
			"get": {
				"summary": "HealthCheck",
				"deprecated": false,
				"description": "",
				"tags": [],
				"parameters": [
					{
						"name": "client_id",
						"in": "header",
						"description": "Unique client id identifying the organisation making the request",
						"required": true,
						"example": "{{client_id}}",
						"schema": {
							"type": "string",
							"minLength": 1,
							"maxLength": 128,
							"pattern": "^[\\w+]+$",
							"default": "{{client_id}}",
							"example": "PoPODqdVmrFXLzdEpGSa"
						}
					},
					{
						"name": "User-Agent",
						"in": "header",
						"description": "Name and version number of system making the request, e.g. RDGRuntime/7.41.2",
						"required": true,
						"example": "{{user-agent}}",
						"schema": {
							"type": "string",
							"pattern": "^[\\x20-\\x7E]+$",
							"minLength": 1,
							"maxLength": 256,
							"default": "{{user-agent}}",
							"example": "PostmanRuntime/7.47.2"
						}
					},
					{
						"name": "X-Correlation-Cust-Id",
						"in": "header",
						"description": "Unique client correlation id that can be used to trace requests",
						"example": "",
						"schema": {
							"type": "string",
							"maxLength": 100,
							"pattern": "^[A-Za-z0-9_-]+$"
						}
					}
				],
				"responses": {
					"200": {
						"description": "Success",
						"content": {
							"application/json": {
								"schema": {
									"type": "object",
									"properties": {
										"version": {
											"type": "integer"
										},
										"message": {
											"type": "string"
										}
									},
									"required": [
										"version",
										"message"
									]
								},
								"example": {
									"version": 1,
									"message": "Service is available"
								}
							}
						},
						"headers": {}
					}
				},
				"security": [
					{
						"bearerAuth": []
					}
				]
			}
		},
		"/railcards/{railcardNumber}/expiry": {
			"post": {
				"summary": "RVS Check Railcard",
				"deprecated": false,
				"description": "This method is used to validate a railcard and return the expiry date if valid\n\nAuthorized clients: Authorised RVS clients",
				"tags": [],
				"parameters": [
					{
						"name": "railcardNumber",
						"in": "path",
						"description": "Railcard Number",
						"required": true,
						"example": "08ZMA0962619701",
						"schema": {
							"type": "string",
							"pattern": "^[a-zA-Z0-9-]+$",
							"minLength": 5,
							"maxLength": 22
						}
					},
					{
						"name": "Authorization",
						"in": "header",
						"description": "Bearer token",
						"required": true,
						"example": "",
						"schema": {
							"type": "string"
						}
					},
					{
						"name": "Accept-Encoding",
						"in": "header",
						"description": "Indicates the content encoding that the client can understand. Specifying gzip will result in compressed (and faster) responses.",
						"required": false,
						"example": "",
						"schema": {
							"type": "string"
						}
					},
					{
						"name": "client_id",
						"in": "header",
						"description": "Unique client id identifying the organisation making the request",
						"required": true,
						"example": "{{client_id}}",
						"schema": {
							"type": "string",
							"minLength": 1,
							"maxLength": 128,
							"pattern": "^[\\w+]+$",
							"default": "{{client_id}}",
							"example": "PoPODqdVmrFXLzdEpGSa"
						}
					},
					{
						"name": "User-Agent",
						"in": "header",
						"description": "Name and version number of system making the request, e.g. RDGRuntime/7.41.2",
						"required": true,
						"example": "{{user-agent}}",
						"schema": {
							"type": "string",
							"pattern": "^[\\x20-\\x7E]+$",
							"minLength": 1,
							"maxLength": 256,
							"default": "{{user-agent}}",
							"example": "PostmanRuntime/7.47.2"
						}
					},
					{
						"name": "X-Correlation-Cust-Id",
						"in": "header",
						"description": "Unique client correlation id that can be used to trace requests",
						"example": "",
						"schema": {
							"type": "string",
							"maxLength": 100,
							"pattern": "^[A-Za-z0-9_-]+$"
						}
					}
				],
				"requestBody": {
					"content": {
						"application/json": {
							"schema": {
								"$ref": "#/components/schemas/RailcardRequest"
							},
							"examples": {}
						}
					}
				},
				"responses": {
					"200": {
						"description": "A valid railcard matching the provided details was found",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/RailcardValidationResponse"
								},
								"example": {
									"railcardType": "TSU",
									"expiresOn": "2026-04-11"
								}
							}
						},
						"headers": {}
					},
					"400": {
						"x-amf-mediaType": "application/json",
						"description": "The server cannot process the request due to a client error",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/Errors"
								}
							}
						},
						"headers": {}
					},
					"401": {
						"x-amf-mediaType": "application/json",
						"description": "The user is not authorised to use this API",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/Errors"
								}
							}
						},
						"headers": {}
					},
					"404": {
						"x-amf-mediaType": "application/json",
						"description": "The server did not find a valid railcard with the provided details",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/Errors"
								}
							}
						},
						"headers": {}
					},
					"500": {
						"x-amf-mediaType": "application/json",
						"description": "The server encountered an unexpected condition that prevented it from fulfilling the request",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/Errors"
								}
							}
						},
						"headers": {}
					}
				},
				"security": []
			}
		},
		"/railcards/validityChanges": {
			"post": {
				"summary": "RVS Validity Changes",
				"deprecated": false,
				"description": "This method is used to retrieve changes in railcard validities during a specified time window.\n\nAuthorized clients: Authorised RVS clients",
				"tags": [],
				"parameters": [
					{
						"name": "limit",
						"in": "query",
						"description": "Used with offset to enable pagination. Specifies how many records to return.",
						"required": true,
						"schema": {
							"type": "integer"
						}
					},
					{
						"name": "offset",
						"in": "query",
						"description": "Used with limit to enable pagination. Specifies which record to start from. It must be set to 0 for the initial request and to the offset returned in the previous response",
						"required": true,
						"schema": {
							"type": "integer"
						}
					},
					{
						"name": "Authorization",
						"in": "header",
						"description": "Bearer token",
						"required": true,
						"example": "",
						"schema": {
							"type": "string"
						}
					},
					{
						"name": "Accept-Encoding",
						"in": "header",
						"description": "Indicates the content encoding that the client can understand. Specifying gzip will result in compressed (and faster) responses.",
						"required": false,
						"example": "",
						"schema": {
							"type": "string"
						}
					},
					{
						"name": "client_id",
						"in": "header",
						"description": "Unique client id identifying the organisation making the request",
						"required": true,
						"example": "{{client_id}}",
						"schema": {
							"type": "string",
							"minLength": 1,
							"maxLength": 128,
							"pattern": "^[\\w+]+$",
							"default": "{{client_id}}",
							"example": "PoPODqdVmrFXLzdEpGSa"
						}
					},
					{
						"name": "User-Agent",
						"in": "header",
						"description": "Name and version number of system making the request, e.g. RDGRuntime/7.41.2",
						"required": true,
						"example": "{{user-agent}}",
						"schema": {
							"type": "string",
							"pattern": "^[\\x20-\\x7E]+$",
							"minLength": 1,
							"maxLength": 256,
							"default": "{{user-agent}}",
							"example": "PostmanRuntime/7.47.2"
						}
					},
					{
						"name": "X-Correlation-Cust-Id",
						"in": "header",
						"description": "Unique client correlation id that can be used to trace requests",
						"example": "",
						"schema": {
							"type": "string",
							"maxLength": 100,
							"pattern": "^[A-Za-z0-9_-]+$"
						}
					}
				],
				"requestBody": {
					"content": {
						"application/json": {
							"schema": {
								"$ref": "#/components/schemas/ValidityChangeRequest"
							},
							"examples": {}
						}
					}
				},
				"responses": {
					"200": {
						"description": "List of railcards whose validity status has changed",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/ValidityChangeResponse"
								}
							}
						},
						"headers": {}
					},
					"400": {
						"x-amf-mediaType": "application/json",
						"description": "The server cannot process the request due to a client error",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/Errors"
								}
							}
						},
						"headers": {}
					},
					"401": {
						"x-amf-mediaType": "application/json",
						"description": "The user is not authorised to use this API",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/Errors"
								}
							}
						},
						"headers": {}
					},
					"404": {
						"x-amf-mediaType": "application/json",
						"description": "The server did not find a valid railcard with the provided details",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/Errors"
								}
							}
						},
						"headers": {}
					},
					"500": {
						"x-amf-mediaType": "application/json",
						"description": "The server encountered an unexpected condition that prevented it from fulfilling the request",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/Errors"
								}
							}
						},
						"headers": {}
					}
				},
				"security": []
			}
		},
		"/railcards/railcardTypes": {
			"get": {
				"summary": "RVS Get Railcard Types",
				"deprecated": false,
				"description": "Retrieve a list of active Railcard types\n\nAuthorized clients: Authorised RVS clients",
				"tags": [],
				"parameters": [
					{
						"name": "Authorization",
						"in": "header",
						"description": "Bearer token",
						"required": true,
						"example": "",
						"schema": {
							"type": "string"
						}
					},
					{
						"name": "Accept-Encoding",
						"in": "header",
						"description": "Indicates the content encoding that the client can understand. Specifying gzip will result in compressed (and faster) responses.",
						"required": false,
						"example": "",
						"schema": {
							"type": "string"
						}
					},
					{
						"name": "client_id",
						"in": "header",
						"description": "Unique client id identifying the organisation making the request",
						"required": true,
						"example": "{{client_id}}",
						"schema": {
							"type": "string",
							"minLength": 1,
							"maxLength": 128,
							"pattern": "^[\\w+]+$",
							"default": "{{client_id}}",
							"example": "PoPODqdVmrFXLzdEpGSa"
						}
					},
					{
						"name": "User-Agent",
						"in": "header",
						"description": "Name and version number of system making the request, e.g. RDGRuntime/7.41.2",
						"required": true,
						"example": "{{user-agent}}",
						"schema": {
							"type": "string",
							"pattern": "^[\\x20-\\x7E]+$",
							"minLength": 1,
							"maxLength": 256,
							"default": "{{user-agent}}",
							"example": "PostmanRuntime/7.47.2"
						}
					},
					{
						"name": "X-Correlation-Cust-Id",
						"in": "header",
						"description": "Unique client correlation id that can be used to trace requests",
						"example": "",
						"schema": {
							"type": "string",
							"maxLength": 100,
							"pattern": "^[A-Za-z0-9_-]+$"
						}
					}
				],
				"responses": {
					"200": {
						"description": "List of railcards whose validity status has changed",
						"content": {
							"application/json": {
								"schema": {
									"type": "array",
									"items": {
										"type": "object",
										"properties": {
											"railcardType": {
												"type": "string",
												"title": "Railcard Type",
												"description": "The type code for the Railcard, this is the Product Code for the Railcard",
												"minLength": 3,
												"maxLength": 3,
												"pattern": "^[A-Z0-9]+$",
												"example": "TSU"
											},
											"railcardTypeName": {
												"type": "string",
												"example": "Young"
											}
										},
										"required": [
											"railcardType",
											"railcardTypeName"
										]
									}
								}
							}
						},
						"headers": {}
					},
					"400": {
						"x-amf-mediaType": "application/json",
						"description": "The server cannot process the request due to a client error",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/Errors"
								}
							}
						},
						"headers": {}
					},
					"401": {
						"x-amf-mediaType": "application/json",
						"description": "The user is not authorised to use this API",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/Errors"
								}
							}
						},
						"headers": {}
					},
					"404": {
						"x-amf-mediaType": "application/json",
						"description": "The server did not find a valid railcard with the provided details",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/Errors"
								}
							}
						},
						"headers": {}
					},
					"500": {
						"x-amf-mediaType": "application/json",
						"description": "The server encountered an unexpected condition that prevented it from fulfilling the request",
						"content": {
							"application/json": {
								"schema": {
									"$ref": "#/components/schemas/Errors"
								}
							}
						},
						"headers": {}
					}
				},
				"security": []
			}
		}
	},
	"components": {
		"schemas": {
			"Error": {
				"title": "RDG Error Object",
				"type": "object",
				"properties": {
					"code": {
						"title": "Error Code",
						"type": "string",
						"description": "A unique (by service) code for an error"
					},
					"message": {
						"title": "Error Message",
						"type": "string",
						"description": "Short description of an error"
					},
					"timestamp": {
						"title": "Error Timestamp",
						"type": "string",
						"format": "date-time",
						"description": "Timestamp of an error"
					},
					"context": {
						"title": "Context",
						"description": "Additional context in relation to the notice.",
						"type": "object",
						"patternProperties": {
							"[a-zA-Z0-9_]*": {
								"type": "string"
							}
						},
						"properties": {}
					}
				}
			},
			"ValidityChangeRequest": {
				"title": "Validity change request",
				"description": "Request list of railcards whose validity has changed within a time window",
				"type": "object",
				"required": [
					"from",
					"to"
				],
				"properties": {
					"from": {
						"description": "Return the from parameter from the database query interface",
						"type": "string",
						"format": "date-time",
						"minLength": 0,
						"maxLength": 255
					},
					"to": {
						"description": "Return the to parameter from the database query interface",
						"type": "string",
						"format": "date-time",
						"minLength": 0,
						"maxLength": 255
					},
					"railcardTypes": {
						"$ref": "#/components/schemas/RailcardTypeList",
						"description": "Product Code"
					},
					"validityChangeTypes": {
						"description": "Determines the Validity Change Types to query and return. <BR/>If empty or parameter not present, this means include all known Validity Change Types",
						"type": "array",
						"items": {
							"$ref": "#/components/schemas/ValidityChangeTypes"
						}
					}
				}
			},
			"ValidityChangeTypes": {
				"type": "string",
				"enum": [
					"VALID_TO_INVALID",
					"INVALID_TO_VALID"
				]
			},
			"RailcardTypeList": {
				"description": "Determines the Railcard Types to query and return. <BR/>If empty or parameter not present, this means include all known Railcards in the system",
				"type": "array",
				"items": {
					"type": "string",
					"description": "The type code for the Railcard, this is the Product Code for the Railcard",
					"minLength": 3,
					"maxLength": 3,
					"pattern": "^[A-Z]+$"
				}
			},
			"ValidityChangeResponse": {
				"title": "Validity change response",
				"description": "List of railcards whose validity has changed within the requested time window",
				"type": "object",
				"required": [
					"from",
					"to",
					"sourceDataSyncTime",
					"validityChanges",
					"offset"
				],
				"properties": {
					"from": {
						"description": "Return the from parameter from the database query interface",
						"type": "string",
						"format": "date-time",
						"minLength": 0,
						"maxLength": 255
					},
					"to": {
						"description": "Return the to parameter from the database query interface",
						"type": "string",
						"format": "date-time",
						"minLength": 0,
						"maxLength": 255
					},
					"offset": {
						"type": "integer"
					},
					"sourceDataSyncTime": {
						"description": "Informs client when the data was last successfully received from all data sources",
						"type": "string",
						"format": "date-time",
						"minLength": 0,
						"maxLength": 255
					},
					"validityChanges": {
						"description": "Requested validity changes",
						"type": "array",
						"minItems": 0,
						"items": {
							"$ref": "#/components/schemas/ValidityChange"
						}
					}
				}
			},
			"ValidityChange": {
				"title": "Validity change",
				"description": "Details of railcards whose validity has changed",
				"type": "object",
				"required": [
					"railcardNumber",
					"railcardType",
					"expiresOn",
					"isValid",
					"newState",
					"changedAt"
				],
				"properties": {
					"railcardNumber": {
						"type": "string",
						"title": "Railcard Number",
						"description": "Identifier for the Railcard",
						"maxLength": 22,
						"minLength": 11,
						"pattern": "^[A-Za-z0-9]+$"
					},
					"railcardType": {
						"type": "string",
						"title": "Railcard Type",
						"description": "The type code for the Railcard, this is the Product Code for the Railcard",
						"minLength": 3,
						"maxLength": 3,
						"pattern": "^[A-Z]+$"
					},
					"expiresOn": {
						"type": "string",
						"title": "Expires On",
						"description": "Date of Railcard expiry",
						"format": "date"
					},
					"isValid": {
						"description": "States whether the new Railcard state is valid or not",
						"type": "boolean"
					},
					"newState": {
						"type": "string",
						"description": "The new Railcard state",
						"minLength": 0,
						"maxLength": 255,
						"pattern": "^[A-Za-z0-9 -]+$"
					},
					"changedAt": {
						"description": "Datetime the change occurred",
						"type": "string",
						"format": "date-time",
						"minLength": 0,
						"maxLength": 255
					}
				}
			},
			"RailcardRequest": {
				"title": "Railcard request",
				"description": "Railcard request details",
				"type": "object",
				"required": [
					"railcardType",
					"expiresOn",
					"holders"
				],
				"properties": {
					"railcardType": {
						"type": "string",
						"title": "Railcard Type",
						"description": "The type code for the Railcard, this is the Product Code for the Railcard",
						"minLength": 3,
						"maxLength": 3,
						"pattern": "^[A-Z0-9]+$",
						"example": "TSU"
					},
					"expiresOn": {
						"type": "string",
						"title": "Expires On",
						"description": "Expiry date for the Railcard",
						"format": "date"
					},
					"holders": {
						"type": "array",
						"items": {
							"$ref": "#/components/schemas/RailcardHolder"
						}
					}
				}
			},
			"Errors": {
				"title": "Error Array",
				"type": "object",
				"properties": {
					"errors": {
						"type": "array",
						"items": {
							"$ref": "#/components/schemas/Error"
						}
					}
				}
			},
			"RailcardHolder": {
				"title": "Railcard Holder",
				"description": "Railcard holder(s) associated with Railcard",
				"type": "object",
				"required": [
					"lastName"
				],
				"properties": {
					"firstName": {
						"type": "string",
						"title": "First Name",
						"description": "First name of a cardholder",
						"maxLength": 100,
						"pattern": "^(?!.*[×÷ˇ˘μ])[A-Za-zÀ-ž .'’\\-]+$"
					},
					"lastName": {
						"type": "string",
						"title": "Last Name",
						"description": "Last name of a cardholder",
						"minLength": 0,
						"maxLength": 100,
						"pattern": "^(?!.*[×÷ˇ˘μ])[A-Za-zÀ-ž .'’\\-]+$"
					}
				}
			},
			"RailcardType": {
				"type": "string",
				"minLength": 3,
				"maxLength": 3,
				"pattern": "^[A-Za-z]*$",
				"example": "TSU"
			},
			"RailcardValidationResponse": {
				"type": "object",
				"properties": {
					"railcardType": {
						"$ref": "#/components/schemas/RailcardType"
					},
					"expiresOn": {
						"type": "string",
						"description": "The date and time the railcard is valid until",
						"format": "date"
					}
				},
				"required": [
					"railcardType",
					"expiresOn"
				]
			}
		},
		"securitySchemes": {
			"bearerAuth": {
				"type": "apiKey",
				"in": "header",
				"name": "Authorization",
				"description": "JWT Authorization header using the Bearer scheme. Example: \"Authorization: Bearer {token}\""
			}
		}
	},
	"servers": [
		{
			"url": "/api/v3"
		}
	],
	"security": []
}