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}: 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' 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: $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 '@referredType': type: string description: The actual type of the target instance when needed for disambiguation. DocumentSpecificationStatusType: type: string description: Possible values for the status of a DocumentSpecification enum: - created - reviewed - approved - published - archived - deleted - received - verified - rejected - unindexed DocumentStatusType: type: string description: Possible values for the status of a Document enum: - created - reviewed - approved - published - archived - deleted ExternalIdentifier: type: object description: An identification of an entity that is owned by or originates in a software system different from the current system, for example a ProductOrder handed off from a commerce platform into an order handling system. The structure identifies the system itself, the nature of the entity within the system (e.g. class name) and the unique ID of the entity within the system. It is anticipated that multiple external IDs can be held for a single entity, e.g. if the entity passed through multiple systems on the way to the current system. In this case the consumer is expected to sequence the IDs in the array in reverse order of provenance, i.e. most recent system first in the list. required: - id properties: id: example: MC2255771199555 type: string description: identification of the entity within the external system. href: type: string format: uri description: Hyperlink reference externalIdentifierType: example: ProductOrder type: string description: Type of the identification, typically would be the type of the entity within the external system owner: example: MagentoCommerce type: string description: Name of the external system that owns the 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 Quantity: type: object description: An amount in a given unit properties: amount: default: 1 type: number format: float description: Numeric value in a given unit units: type: string description: Unit RelatedEntity: type: object description: A reference to an entity, where the type of the entity is not known in advance. required: - '@referredType' - id - role properties: id: type: string description: unique identifier href: type: string format: uri description: Hyperlink reference name: type: string description: Name of the related entity. role: type: string description: The role of an 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. RelatedParty: type: object description: Related Entity reference. A related party defines party or party role linked to a specific entity. required: - '@referredType' - id properties: id: type: string description: unique identifier href: type: string format: uri description: Hyperlink reference name: type: string description: Name of the related entity. role: type: string description: Role played by the related party '@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. TargetEntitySchema: type: object description: The reference object to the schema and type of target entity which is described by a specification required: - '@schemaLocation' - '@type' properties: '@schemaLocation': type: string description: This field provides a link to the schema describing the target entity '@type': type: string description: Class type of the target entity TimePeriod: type: object description: A period of time, either as a deadline (endDateTime only) a startDateTime only, or both properties: endDateTime: example: '1985-04-12T23:20:50.52Z' type: string format: date-time description: End of the time period, using IETC-RFC-3339 format startDateTime: example: '1985-04-12T23:20:50.52Z' type: string format: date-time description: Start of the time period, using IETC-RFC-3339 format Error: description: Used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx) type: object required: - code - reason properties: code: type: string description: Application relevant detail, defined in the API or a common list. reason: type: string description: Explanation of the reason for the error which can be shown to a client user. message: type: string description: More details and corrective actions related to the error which can be shown to a client user. status: type: string description: HTTP Error code extension referenceError: type: string format: uri description: URI of documentation describing the error. '@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 entity name.