swagger: '2.0'
info:
title: Document
description: TMF667 Document API describes the meta-data of a Document, such as the name, creationDate and lifecycle status. The (typically binary) body of this document (such as a Word.doc, PDF, Video clip, or Image) will be held in the associated Attachment(s) either by Ref or Value. If by value - the binary content is held in the Attachment.content. If by reference, the Attachment.url might point to a (file:) or remote (http:) pointer to the Document media.\n\n A Document may be associated with a DocumentSpecification, which will detail the characteristics of that type of Document (an Image may have a width, height and format; a Video may have a length and format).\n A Document has a collection of RelatedParty's, for roles such as author, reviewer, publisher, and a lifecycle status to take the document through a simple set of production stages.
version: 1.0.0
host: mtn.com
basePath: /tmf-api/document/v4/
schemes:
- https
consumes:
- application/json;charset=utf-8
produces:
- application/json;charset=utf-8
tags:
- name: document
paths:
/document/{id}:
get:
operationId: retrieveDocument
summary: Retrieves/Downloads a document by ID
description: >-
This operation retrieves a Document entity.
tags:
- document
parameters:
- name: transactionId
description: A unique to identify each request for tracing and reporting
required: false
in: header
type: string
- name: id
description: Identifier of the document
required: true
type: string
in: path
- name: queryText
description: Rendition of document to be downloaded
required: true
x-example: primary
type: string
in: query
responses:
'200':
description: Success
schema:
allOf:
- $ref: '#/definitions/ApiResponse'
- type: object
properties:
data:
type: array
items:
$ref: '#/definitions/Document2'
'400':
description: Bad Request
schema:
$ref: '#/definitions/Error2'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/Error2'
'403':
description: Forbidden
schema:
$ref: '#/definitions/Error2'
'404':
description: Not Found
schema:
$ref: '#/definitions/Error2'
'405':
description: Method Not allowed
schema:
$ref: '#/definitions/Error2'
'409':
description: Conflict
schema:
$ref: '#/definitions/Error2'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/Error2'
patch:
operationId: patchDocument
summary: Updates partially a Document
description: This operation updates partially a Document entity.
tags:
- document
parameters:
- name: id
description: Identifier of the Document at Profile Level
required: true
type: string
in: path
- name: profileType
description: Identifier of the Profile Type
required: true
type: string
in: query
enum:
- Account Level
- Service Level
- Customer Level
- Termination
- name: document
description: The Document to be updated
required: true
schema:
$ref: '#/definitions/Document_Update'
in: body
responses:
'200':
description: Updated
schema:
$ref: '#/definitions/Document'
'400':
description: Bad Request
schema:
$ref: '#/definitions/Error'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/Error'
'403':
description: Forbidden
schema:
$ref: '#/definitions/Error'
'404':
description: Not Found
schema:
$ref: '#/definitions/Error'
'405':
description: Method Not allowed
schema:
$ref: '#/definitions/Error'
'409':
description: Conflict
schema:
$ref: '#/definitions/Error'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/Error'
/document:
get:
operationId: listDocument
summary: List or find document objects
description: This operation lists or finds document entities
tags:
- document
parameters:
- name: queryText
description: Base64 encoded query param to send query logic to WCC
required: true
in: query
type: string
x-example: eFNvdXJjZVJlZ
- name: transactionId
description: A unique to identify each request for tracing and reporting
required: false
in: header
type: string
responses:
'200':
description: Success
headers:
X-Result-Count:
description: Actual number of items returned in the response body
type: integer
X-Total-Count:
description: Total number of items matching criteria
type: integer
schema:
allOf:
- $ref: '#/definitions/ApiResponse'
- type: object
properties:
data:
type: array
items:
$ref: '#/definitions/Document2'
'400':
description: Bad Request
schema:
$ref: '#/definitions/Error2'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/Error2'
'403':
description: Forbidden
schema:
$ref: '#/definitions/Error2'
'404':
description: Not Found
schema:
$ref: '#/definitions/Error2'
'405':
description: Method Not allowed
schema:
$ref: '#/definitions/Error2'
'409':
description: Conflict
schema:
$ref: '#/definitions/Error2'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/Error2'
post:
operationId: createDocument
summary: Creates a Document
description: This operation creates a Document entity.
tags:
- document
parameters:
- name: transactionId
description: A unique to identify each request for tracing and reporting
required: false
in: header
type: string
- name: uploadType
description: This has to be set to UPLOAD_BASE64 if the content of the document is uploaded as base64. Not required if the file is uploaded from a shared location
required: false
in: header
type: string
x-example: UPLOAD_BASE64
- name: document
description: The Document to be created
required: true
schema:
$ref: '#/definitions/Document_Create'
in: body
responses:
'200':
description: Success
schema:
$ref: '#/definitions/ApiResponse'
'400':
description: Bad Request
schema:
$ref: '#/definitions/Error2'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/Error2'
'403':
description: Forbidden
schema:
$ref: '#/definitions/Error2'
'405':
description: Method Not allowed
schema:
$ref: '#/definitions/Error2'
'409':
description: Conflict
schema:
$ref: '#/definitions/Error2'
'500':
description: Internal Server Error
schema:
$ref: '#/definitions/Error2'
definitions:
CategoryRef:
type: object
description: The category for grouping recommendations
properties:
id:
type: string
description: unique identifier
href:
type: string
format: uri
description: Hyperlink reference
name:
type: string
description: Name of the related entity.
version:
type: string
description: Category version
'@baseType':
type: string
description: When sub-classing, this defines the super-class
'@schemaLocation':
type: string
format: uri
description: A URI to a JSON-Schema file that defines additional attributes and relationships
'@type':
type: string
description: When sub-classing, this defines the sub-class Extensible name
'@referredType':
type: string
description: The actual type of the target instance when needed for disambiguation.
required:
- id
Characteristic:
type: object
description: Describes a given characteristic of an object or entity through a name/value pair.
required:
- name
- value
properties:
id:
type: string
description: Unique identifier of the characteristic
name:
type: string
description: Name of the characteristic
valueType:
type: string
description: Data type of the value of the characteristic
characteristicRelationship:
type: array
items:
$ref: '#/definitions/CharacteristicRelationship'
'@baseType':
type: string
description: When sub-classing, this defines the super-class
'@schemaLocation':
type: string
format: uri
description: A URI to a JSON-Schema file that defines additional attributes and relationships
'@type':
type: string
description: When sub-classing, this defines the sub-class Extensible name
CharacteristicRelationship:
type: object
description: Another Characteristic that is related to the current Characteristic;
properties:
id:
type: string
description: Unique identifier of the characteristic
href:
type: string
format: uri
description: Hyperlink reference
relationshipType:
type: string
description: The type of relationship
'@baseType':
type: string
description: When sub-classing, this defines the super-class
'@schemaLocation':
type: string
format: uri
description: A URI to a JSON-Schema file that defines additional attributes and relationships
'@type':
type: string
description: When sub-classing, this defines the sub-class Extensible name
CharacteristicSpecification:
type: object
description: This class defines a characteristic specification.
properties:
id:
type: string
description: Unique ID for the characteristic
configurable:
type: boolean
description: If true, the Boolean indicates that the target Characteristic is configurable
description:
type: string
description: A narrative that explains the CharacteristicSpecification.
extensible:
type: boolean
description: An indicator that specifies that the values for the characteristic can be extended by adding new values when instantiating a characteristic for a resource.
isUnique:
type: boolean
description: Specifies if the value of this characteristic is unique across all entities instantiated from the specification that uses this characteristc. For example, consider a ProductSpecification for a set-top box, with a CharacteristicSpecification cardID. Each set-top box must have a different value for cardID, so this isUnique attribute would be set to true for the characteristic.
maxCardinality:
type: integer
description: The maximum number of instances a CharacteristicValue can take on. For example, zero to five phone numbers in a group calling plan, where five is the value for the maxCardinality.
minCardinality:
type: integer
description: The minimum number of instances a CharacteristicValue can take on. For example, zero to five phone numbers in a group calling plan, where zero is the value for the minCardinality.
name:
type: string
description: A word, term, or phrase by which this characteristic specification is known and distinguished from other characteristic specifications.
regex:
type: string
description: A rule or principle represented in regular expression used to derive the value of a characteristic value.
valueType:
type: string
description: A kind of value that the characteristic can take on, such as numeric, text and so forth
charSpecRelationship:
type: array
items:
$ref: '#/definitions/CharacteristicSpecificationRelationship'
description: An aggregation, migration, substitution, dependency or exclusivity relationship between/among Specification Characteristics.
characteristicValueSpecification:
type: array
items:
$ref: '#/definitions/CharacteristicValueSpecification'
description: A CharacteristicValueSpecification object is used to define a set of attributes, each of which can be assigned to a corresponding set of attributes in a CharacteristicSpecification object. The values of the attributes in the CharacteristicValueSpecification object describe the values of the attributes that a corresponding Characteristic object can take on.
validFor:
$ref: '#/definitions/TimePeriod'
description: The period of time for which a characteristic is applicable.
'@baseType':
type: string
description: When sub-classing, this defines the super-class
'@schemaLocation':
type: string
format: uri
description: A URI to a JSON-Schema file that defines additional attributes and relationships
'@type':
type: string
description: When sub-classing, this defines the sub-class Extensible name
'@valueSchemaLocation':
type: string
description: This (optional) field provides a link to the schema describing the value type.
CharacteristicSpecificationBase:
type: object
description: This class defines a characteristic specification.
properties:
id:
type: string
description: Unique ID for the characteristic
configurable:
type: boolean
description: If true, the Boolean indicates that the target Characteristic is configurable
description:
type: string
description: A narrative that explains the CharacteristicSpecification.
extensible:
type: boolean
description: An indicator that specifies that the values for the characteristic can be extended by adding new values when instantiating a characteristic for a resource.
isUnique:
type: boolean
description: Specifies if the value of this characteristic is unique across all entities instantiated from the specification that uses this characteristc. For example, consider a ProductSpecification for a set-top box, with a CharacteristicSpecification cardID. Each set-top box must have a different value for cardID, so this isUnique attribute would be set to true for the characteristic.
maxCardinality:
type: integer
description: The maximum number of instances a CharacteristicValue can take on. For example, zero to five phone numbers in a group calling plan, where five is the value for the maxCardinality.
minCardinality:
type: integer
description: The minimum number of instances a CharacteristicValue can take on. For example, zero to five phone numbers in a group calling plan, where zero is the value for the minCardinality.
name:
type: string
description: A word, term, or phrase by which this characteristic specification is known and distinguished from other characteristic specifications.
regex:
type: string
description: A rule or principle represented in regular expression used to derive the value of a characteristic value.
valueType:
type: string
description: A kind of value that the characteristic can take on, such as numeric, text and so forth
validFor:
$ref: '#/definitions/TimePeriod'
description: The period of time for which a characteristic is applicable.
'@baseType':
type: string
description: When sub-classing, this defines the super-class
'@schemaLocation':
type: string
format: uri
description: A URI to a JSON-Schema file that defines additional attributes and relationships
'@type':
type: string
description: When sub-classing, this defines the sub-class Extensible name
'@valueSchemaLocation':
type: string
description: This (optional) field provides a link to the schema describing the value type.
CharacteristicSpecificationRelationship:
type: object
description: An aggregation, migration, substitution, dependency or exclusivity relationship between/among Characteristic specifications. The specification characteristic is embedded within the specification whose ID and href are in this entity, and identified by its ID.
properties:
characteristicSpecificationId:
type: string
description: Unique identifier of the characteristic within the specification
name:
type: string
description: Name of the target characteristic within the specification
parentSpecificationHref:
type: string
format: uri
description: Hyperlink reference to the parent specification containing the target characteristic
parentSpecificationId:
type: string
description: Unique identifier of the parent specification containing the target characteristic
relationshipType:
type: string
description: Type of relationship such as aggregation, migration, substitution, dependency, exclusivity
validFor:
$ref: '#/definitions/TimePeriod'
description: The period for which the object is valid
'@baseType':
type: string
description: When sub-classing, this defines the super-class
'@schemaLocation':
type: string
format: uri
description: A URI to a JSON-Schema file that defines additional attributes and relationships
'@type':
type: string
description: When sub-classing, this defines the sub-class Extensible name
CharacteristicValueSpecification:
type: object
description: specification of a value (number or text or an object) that can be assigned to a Characteristic.
properties:
isDefault:
type: boolean
description: If true, the Boolean Indicates if the value is the default value for a characteristic
rangeInterval:
type: string
description: An indicator that specifies the inclusion or exclusion of the valueFrom and valueTo attributes. If applicable, possible values are "open", "closed", "closedBottom" and "closedTop".
regex:
type: string
description: A regular expression constraint for given value
unitOfMeasure:
type: string
description: A length, surface, volume, dry measure, liquid measure, money, weight, time, and the like. In general, a determinate quantity or magnitude of the kind designated, taken as a standard of comparison for others of the same kind, in assigning to them numerical values, as 1 foot, 1 yard, 1 mile, 1 square foot.
valueFrom:
type: integer
description: The low range value that a characteristic can take on
valueTo:
type: integer
description: The upper range value that a characteristic can take on
valueType:
type: string
description: A kind of value that the characteristic value can take on, such as numeric, text and so forth
validFor:
$ref: '#/definitions/TimePeriod'
description: The period of time for which a value is applicable.
'@baseType':
type: string
description: When sub-classing, this defines the super-class
'@schemaLocation':
type: string
format: uri
description: A URI to a JSON-Schema file that defines additional attributes and relationships
'@type':
type: string
description: When sub-classing, this defines the sub-class Extensible name
ConstraintRef:
type: object
description: Constraint reference. The Constraint resource represents a policy/rule applied to an entity or entity spec.
properties:
id:
type: string
description: unique identifier
href:
type: string
format: uri
description: Hyperlink reference
name:
type: string
description: Name of the related entity.
version:
type: string
description: constraint version
'@baseType':
type: string
description: When sub-classing, this defines the super-class
'@schemaLocation':
type: string
format: uri
description: A URI to a JSON-Schema file that defines additional attributes and relationships
'@type':
type: string
description: When sub-classing, this defines the sub-class Extensible name
'@referredType':
type: string
description: The actual type of the target instance when needed for disambiguation.
required:
- id
Document:
type: object
description: |-
A Document describes the meta-data of a Document - such as the name, creationDate and lifecycle status.
The (typically binary) body of this document (such as a Word.doc, PDF, Video clip, or Image) will be held in the associated Attachment(s) either by Ref or Value. If by value - the binary content is held in the Attachment.content. If by reference, the Attachment.url might point to a (file:) or remote (http:) pointer to the Document media.
A Document may be associated with a DocumentSpecification, which will detail the characteristics of that type of Document (an Image may have a width, height and format; a Video may have a length and format).
A Document has a collection of RelatedParty's, for roles such as author, reviewer, publisher; and a lifecycle status to take the document through a simple set of production stages.
properties:
id:
type: string
description: unique identifier
href:
type: string
format: uri
description: Hyperlink reference
creationDate:
type: string
format: date-time
description: The date and time the document was created. A date and time formatted in compliance with the ISO8601 standard must be used.
description:
type: string
description: free-text description of the document
documentType:
type: string
description: Name of the document type
lastUpdate:
type: string
format: date-time
description: The date and time the document was last modified. A date and time formatted in compliance with the ISO8601 standard must be used.
name:
type: string
description: A string used to give a name to the document
version:
type: string
description: A particular form or variety of an artefact that is different from others or from the original. The form represents differences in properties that characterize an artefact, that are not enough to warrant creating a new artefact
category:
type: array
items:
$ref: '#/definitions/CategoryRef'
characteristic:
type: array
items:
$ref: '#/definitions/Characteristic'
document:
type: array
items:
$ref: '#/definitions/DocumentRef'
documentSpecification:
$ref: '#/definitions/DocumentSpecificationRefOrValue'
externalIdentifier:
type: array
items:
$ref: '#/definitions/ExternalIdentifier'
relatedEntity:
type: array
items:
$ref: '#/definitions/RelatedEntity'
relatedParty:
type: array
items:
$ref: '#/definitions/RelatedParty'
status:
$ref: '#/definitions/DocumentStatusType'
description: The life cycle state of the document
'@baseType':
type: string
description: When sub-classing, this defines the super-class
'@schemaLocation':
type: string
format: uri
description: A URI to a JSON-Schema file that defines additional attributes and relationships
'@type':
type: string
description: When sub-classing, this defines the sub-class Extensible name
Document_Update:
type: object
description: |-
A Document describes the meta-data of a Document - such as the name, creationDate and lifecycle status.
The (typically binary) body of this document (such as a Word.doc, PDF, Video clip, or Image) will be held in the associated Attachment(s) either by Ref or Value. If by value - the binary content is held in the Attachment.content. If by reference, the Attachment.url might point to a (file:) or remote (http:) pointer to the Document media.
A Document may be associated with a DocumentSpecification, which will detail the characteristics of that type of Document (an Image may have a width, height and format; a Video may have a length and format).
A Document has a collection of RelatedParty's, for roles such as author, reviewer, publisher; and a lifecycle status to take the document through a simple set of production stages.
Skipped properties: id,href,@type,@baseType,@schemaLocation
properties:
documentType:
type: string
description: Name of the document type
enum:
- POID
- POA
documentName:
type: string
description: A string used to give a name to the document
enum:
- National ID
- Passport
- Payam Letter
documentID:
type: string
description: A unique identifier to the document mentioned in document name.
document:
type: array
items:
$ref: '#/definitions/DocumentRef'
documentSpecification:
$ref: '#/definitions/DocumentSpecification'
DocumentRef:
type: object
properties:
refId:
type: string
description: Identifier of the document in other system
href:
type: string
description: The URI for the object itself.
name:
type: string
description: Name of the related entity.
'@baseType':
type: string
description: When sub-classing, this defines the super-class
'@schemaLocation':
type: string
format: uri
description: A URI to a JSON-Schema file that defines additional attributes and relationships
'@type':
type: string
description: When sub-classing, this defines the sub-class Extensible name
'@referredType':
type: string
description: The actual type of the target instance when needed for disambiguation.
required:
- refId
DocumentSpecification:
type: object
description: 'A DocumentSpecification provides the characteristics and constraints that describe a particular type of Document. It follows the EntitySpecification pattern, so allows you to define the characteristics expected, as well as the nature of the values of those characteristics (eg: integer range [valueFrom/valueTo], regular expression or unitOfMeasure).'
properties:
id:
type: string
description: unique identifier
href:
type: string
format: uri
description: Hyperlink reference
description:
type: string
description: Description of the specification
isBundle:
type: boolean
description: isBundle determines whether specification represents a single specification (false), or a bundle of specifications (true).
lastUpdate:
type: string
format: date-time
description: Date and time of the last update of the specification
name:
example: Image Specification
type: string
description: The name of the DocumentSpecification
version:
example: 1.0.0
type: string
description: The version of the DocumentSpecification
constraint:
type: array
items:
$ref: '#/definitions/ConstraintRef'
description: This is a list of constraint references applied to this specification
lifecycleStatus:
example: approved
$ref: '#/definitions/DocumentSpecificationStatusType'
description: The current lifecycle status of this DocumentSpecification
relatedParty:
type: array
items:
$ref: '#/definitions/RelatedParty'
description: Parties who manage or otherwise have an interest in this specification
specCharacteristic:
type: array
items:
$ref: '#/definitions/CharacteristicSpecification'
description: List of characteristics that the entity can take
targetEntitySchema:
$ref: '#/definitions/TargetEntitySchema'
description: Pointer to a schema that defines the target entity
validFor:
$ref: '#/definitions/TimePeriod'
description: The period for which this REST resource is valid
'@baseType':
type: string
description: When sub-classing, this defines the super-class
'@schemaLocation':
type: string
format: uri
description: A URI to a JSON-Schema file that defines additional attributes and relationships
'@type':
type: string
description: When sub-classing, this defines the sub-class Extensible name
DocumentSpecificationRef:
type: object
description: A DocumentSpecificationRef provides a reference to a DocumentSpefication
properties:
id:
type: string
description: unique identifier
href:
type: string
format: uri
description: Hyperlink reference
name:
type: string
description: Name of the related entity.
'@baseType':
type: string
description: When sub-classing, this defines the super-class
'@schemaLocation':
type: string
format: uri
description: A URI to a JSON-Schema file that defines additional attributes and relationships
'@type':
type: string
description: When sub-classing, this defines the sub-class Extensible name
'@referredType':
type: string
description: The actual type of the target instance when needed for disambiguation.
required:
- id
DocumentSpecificationRefOrValue:
type: object
description: A DocumentSpecificationRefOrValue where you can select between a DocumentSpecification (by Value) or a DocumentSpecificationRef (by Reference)
properties:
id:
type: string
description: unique identifier
href:
type: string
format: uri
description: Hyperlink reference
description:
type: string
description: Description of the specification
isBundle:
type: boolean
description: isBundle determines whether specification represents a single specification (false), or a bundle of specifications (true).
lastUpdate:
type: string
format: date-time
description: Date and time of the last update of the specification
name:
type: string
description: Name given to the specification
version:
type: string
description: specification version
constraint:
type: array
items:
# --- truncated at 32 KB (55 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mtn-group/refs/heads/main/openapi/mtn-group-document-managment.yml