RFC 4153

XML Voucher: Generic Voucher Language

📅 published September 2005, from ietf

RFC 4153: XML Voucher: Generic Voucher Language 🎀

okay bestie, RFC 4153 is a September 2005 Informational doc, so it's sharing info and it's not a binding standard 💅. It came from K. Fujimura at NTT, M. Terada at NTT DoCoMo, and D. Eastlake 3rd at Motorola Laboratories. The authors are a whole international girlboss squad 🌈. It doesn't list anything it obsoletes or updates, so it's standing on its own ✨.

Status of This Memo 📝

this memo gives info to the Internet community 🫶. it does not specify an Internet standard of any kind, and distribution of it is unlimited 🦋.

Copyright Notice ©️

Abstract 🌸

this doc sets out rules for defining voucher properties in XML syntax ✨. a voucher is a logical entity that represents a right to claim goods or services 🎫. vouchers can carry a wild range of electronic value, like coupons, tickets, loyalty points, and gift certificates 🍓, and they often need processing during payment and/or delivery transactions 💸.

Table of Contents 🧚

   1.  Introduction .................................................  2
   2.  Processing Model .............................................  2
   3.  Trust Model ..................................................  4
   4.  Component Structure ..........................................  4
   5.  Syntax Overview and Examples .................................  6
   6.  Syntax and Semantics .........................................  8
       6.1. <Voucher> ...............................................  8
       6.2. <Title> .................................................  9
       6.3. <Description> ...........................................  9
       6.4. <Provider> ..............................................  9
       6.5. <Issuer> ................................................ 10
       6.6. <Holder> ................................................ 10
       6.7. <Collector> ............................................. 11
       6.8. <Value> ................................................. 11
            6.8.1. <Ratio> .......................................... 13
            6.8.2. <Fixed> .......................................... 13

       6.9. <Merchandise> ........................................... 14
       6.10. <ValidPeriod> .......................................... 14
       6.11. <Conditions> ........................................... 15
   7.  IANA Considerations .......................................... 15
   8.  VTS Schema Example ........................................... 18
   9.  Security Considerations ...................................... 18
   10. Acknowledgements ............................................. 19
   11. Normative References ......................................... 19
   12. Informative References ....................................... 20

1. Introduction ✨

this doc sets out rules for defining voucher properties in XML syntax 🎀. the background and motivation are covered in [VTS] 📚.

a voucher is a logical entity that represents a certain right, and the Voucher Trading System (VTS) is what logically manages it 🦋. the issuer generates a voucher, users trade it around, and then the collector finally collects it using VTS 💅.

this doc defines the syntax and semantics of the Voucher Component, which describes what a voucher means and how it gets processed, in XML syntax [XML] 🧚. a Voucher Component defines the properties that must be satisfied so the voucher can be processed by VTS or other trading systems, like a wallet or a merchant system 👛. VTS definitions and models are also in [VTS] 🌈.

Note: this doc uses "voucher" to mean an "instance of voucher", whose meaning is defined by the Voucher Component 💜. in other words, a Voucher Component is NOT a voucher, and VTS can issue and manage multiple vouchers using the same Voucher Component 🔥.

the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this doc are to be interpreted as described in [RFC2119] 🫶.

2. Processing Model 🌸

there are lots of ways to implement VTS, and the tech keeps changing 🔄. for discount coupons or event tickets, for example, a smartcard-based offline VTS is often preferred 🎫, while for bonds or securities, a centralized online VTS is preferred 📈. it's impractical to define standard protocols for issuing, transferring, or redeeming vouchers right now 🙈.

so for implementation flexibility, this doc assumes a modular wallet architecture where multiple VTSes can be added as plug-ins 🧩. instead of specifying one standard voucher transfer protocol, two specs get standardized: Voucher Component and VTS-API (Figure 1) 💖.

after the sender and receiver agree on which vouchers are being traded and which VTS to use, the issuing system or wallet system asks the matching VTS plug-in to permit the issue, transfer, or redeem transactions through the VTS API 🦋. the VTS then rewrites the ownership of the vouchers using its VTS-specific protocol 🔁. finally, a completion event gets sent to the wallet systems or issuing/collecting systems 🎉.

this doc only describes the Voucher Component spec 🎀. the VTS-API spec is defined in [VTS-API] 📖.

   Sender wallet/Issuing system      Receiver wallet/Collecting system
   +---------------------------+       +---------------------------+
   |                           |       |                           |
   |  |                    Voucher Component                    |  |
   |  |            (Specifies VTS Provider and Promise)         |  |
   |  |-------------------------------------------------------->|  |
   |  |                        |       |                        |  |
   |  |         Intention to receive and payment (option)       |  |
   |  |<- - - - - - - - - - - - - - - - - - - - - - - - - - - - |  |
   |  |                        |       |                        |  |
   |  |                        |       |                        |  |
   |  | Issue/transfer/  VTS   |       |   VTS      Register    |  |
   |  | redeem request   plug-in       |   plug-in  Listener(*1)|  |
   |  |------------------>|    |       |    |<------------------|  |
   |  | (VTS-API)         |<- - - - - - - ->|         (VTS-API) |  |
   |  |                   | VTS-specific    |                   |  |
   |  |                   | protocol if VTS |                   |  |
   |  |                   | is distributed  |                   |  |
   |  |  Result           |<- - - - - - - ->|       Notify(*2)  |  |
   |  |<------------------|    |       |    |------------------>|  |
   +---------------------------+       +---------------------------+

   (*1) Registration is optional.  Note also that the VTS plug-ins are
        usually pre-registered when the wallet or collecting system
        is started.

   (*2) If a listener is registered.

           Figure 1. Wallet architecture with VTS plug-ins

3. Trust Model 🔐

a voucher is trusted if the Issuer and the VTS Provider are trusted 🤝. the Issuer is responsible for what's in the voucher, and the VTS Provider is responsible for stopping ownership from being assigned to multiple users 🚫👯.

how much trust the Issuer and VTS Provider need depends on the type (or Promise) of the voucher 📊. to give the verifier the info it needs, the conditions for the Issuer and VTS Provider get specified in the Voucher Component and handed over as input to the verifier, like a wallet system or other software 🧾. so a voucher's trust gets verified through the Voucher Component 💅. this model lets trading partners verify their trust in a voucher no matter how much they trust each other 🌈.

this doc assumes the Voucher Component is the root of trust 🌳. if a malicious user could alter the Voucher Component, a forged voucher could be verified as valid 😱💀.

When a Voucher Component comes from the trusted VTS Provider, Issuer, or a trusted third party, a secure communication channel (e.g., [TLS], [IPSEC], or object security, such as [XMLDSIG]) should be used to prevent alteration during delivery 🔒.

Note: the Voucher Component doesn't have to be sent by the voucher's sender 📬. also, a set of trusted Voucher Components can be downloaded before a transaction happens ⭐.

Part 1 of 4 is done 🎀 more parts are coming, so stay tuned, bestie 💖

4. Component Structure 🎀

Okay bestie, this is where the Voucher Component gets its outfit 💅. It tells you what a voucher is worth when someone redeems it, and that's it. It covers:

how much value or how many items can be claimed in exchange for the voucher, and
the restrictions on the voucher:
- participants (VTS Provider, Issuer, Holder, and Collector),
- objects (merchandise) to be claimed,
- the time when it's valid (validity period), and
- others.

It also has the common stuff wallet systems need to show and manage vouchers, which is the title and description of each voucher ✨.

The Voucher Component is made of these pieces:

Title Component 💖 Gives the title of the voucher. It's mainly there so wallet systems can list the stuff stored in them.

Description Component 🌸 Gives a short description of the voucher. Same deal, it's mainly for listing the entities stored in a wallet system.

Provider Component 🧚 Restricts which VTS Provider (or VTS plug-in) can be used to trade the voucher.

Issuer Component 👑 Restricts the Issuer of the voucher.

Holder Component 🫶 Restricts the Holder of the voucher.

Collector Component 🦋 Restricts the Collector of the voucher.

Value Component 💜 Gives the value of each voucher. There are two kinds: fixed and ratio. A fixed value specifies the currency and the figure. A ratio value specifies the discount ratio for the matching merchandise.

The Value Component also says how many vouchers you need to redeem to claim the merchandise or monetary value from the Merchandise Component or Value Component. If "n" (>0) is specified, you can claim it in exchange for "n sheets of" vouchers. If "0" is specified, it can be used repeatedly. Iconic, honestly 🔥.

Merchandise Component 🍓 Restricts the object to be claimed. The domain-specific meaning of the voucher (like a reference number for merchandise or a seat number for an event ticket) identifies the merchandise you get when you redeem it.

ValidPeriod Component ⭐ Restricts the validity period of the voucher, so the start date and end date.

Condition Component 🙈 Covers any other applicable restrictions. It's meant for the contract between the issuer and holder of the voucher, written in natural language.

With those Components you can define semantics for lots of voucher types, as shown in Table 1 💖.

   +----------------+--------------------------------+---------------+
   |                |             Value              |  Restrictions |
   |                +-----+---------------+----------+---------------+
   |   Examples     |Ratio|    Fixed      |Number    |  Merchandise  |
   |                |     +------+--------+needed for|               |
   |                |     |Amount|Currency|redemption|               |
   +----------------+-----+------+--------+----------+---------------+
   |Gift certificate|     |   25 |  USD   |        1 |(Not specified)|
   |Loyalty point   |     |    1 |  AUD   |       10 |(Not specified)|
   |Member card     |  20%|      |        |        0 |(Not specified)|
   |Coupon          |  30%|      |        |        1 |Beef 500g      |
   |Event ticket    | 100%|      |        |        1 |Hall A, S ,K23 |
   |Exchange ticket | 100%|      |        |        1 |ISBN:0071355014|
   +----------------+-----+------+--------+----------+---------------+

          Table 1. Examples of vouchers and their properties

5. Syntax Overview and Examples 🌈

This section gives you an overview and some examples of Voucher Components. The formal syntax and semantics are in Sections 6 and 7 🫶.

Voucher Components are written with the <Voucher> element, which looks like this (where "?" means zero or one occurrence):

   <Voucher>
     (Title)
     (Description)?
     (Provider)
     (Issuer)?
     (Holder)?
     (Collector)?
     (Value)
     (Merchandise)?
     (ValidPeriod)?
     (Conditions)?
   </Voucher>

Here's an example of a Voucher Component 💅. It's a five-dollar discount coupon for a specific item, a book with ISBN number 0071355014. The coupon is valid from April 1, 2001, to March 31, 2002. To claim it, one voucher must be spent.

   <?xml version="1.0" encoding="UTF-8"?>
   <Voucher xmlns="urn:ietf:params:xml:ns:vts-lang"
            xmlns:vts="http://www.example.com/vts">
     <Title>IOTP Book Coupon</Title>
     <Description>$5 off IOTP Book</Description>
     <Provider name="Voucher Exchanger 2002">
       <vts:Version>VE2.31</vts:Version>
     </Provider>
     <Issuer name="Alice Book Center, Ltd.">
       <vts:KeyInfo>
         1DA8DFCF95521014BBB7171B95545E8D61AE803F
       </vts:KeyInfo>
     </Issuer>
     <Collector name="Alice Book Center, Ltd."/>
     <Value type="discount" spend="1">
       <Fixed amount="5" currency="USD"/>
     </Value>
     <Merchandise>
       <bk:Book xmlns:bk="http://www.example.com/bk"
                bk:isbn="0071355014"/>
     </Merchandise>
     <ValidPeriod start="2002-04-01" end="2003-03-31"/>
     <Conditions>
       The value of this coupon is subject to tax.
     </Conditions>
   </Voucher>

6. Syntax and Semantics 🔥

The general structure of an XML Voucher Component is in Section 4. This section goes into the features of the Voucher Component 💖. Features described here MUST be implemented unless otherwise indicated. The syntax is defined via [XML-Schema-1] [XML-Schema-2]. For clarity, unqualified elements in schema definitions are in the XML schema namespace:

   xmlns="http://www.w3.org/2001/XMLSchema"

References to the XML Voucher schema defined here use the prefix "gvl" and are in this namespace:

   xmlns:gvl="urn:ietf:params:xml:ns:vts-lang"

This namespace URI for the elements defined by this document is a URN [URN] that uses the namespace identifier 'ietf', defined by [URN-NS-IETF] and extended by [XML-Registry]. 🧚

This namespace is also used for unqualified elements in voucher examples.

6.1. <Voucher> 🎀

The <Voucher> element contains <Title>, <Provider>, and <Value> elements, and optionally contains <Description>, <Issuer>, <Holder>, <Collector>, <ValidPeriod>, and <Condition> elements. We'll cover these sub-elements in the sections that follow ✨.

The <Voucher> element is defined by this schema:

   <element name="Voucher" type="gvl:VoucherType"/>
   <complexType name="VoucherType">
    <sequence>
     <element ref="gvl:Title"/>
     <element ref="gvl:Description" minOccurs="0"/>
     <element ref="gvl:Provider"/>
     <element ref="gvl:Issuer" minOccurs="0"/>
     <element ref="gvl:Holder" minOccurs="0"/>
     <element ref="gvl:Collector" minOccurs="0"/>
     <element ref="gvl:Value"/>
     <element ref="gvl:Merchandise" minOccurs="0"/>
     <element ref="gvl:ValidPeriod" minOccurs="0"/>
     <element ref="gvl:Conditions"  minOccurs="0"/>
    </sequence>
   </complexType>

6.2. <Title> 💜

The <Title> element contains a simpletext title of the voucher. It's mainly for listing the entities stored in a wallet system 📚.

The <Title> element has no attribute.

The <Title> element is defined by this schema:

   <element name="Title" type="string"/>

6.3. <Description> 🌸

The <Description> element contains a simpletext description of the voucher. It's mainly for listing the entities stored in a wallet system.

The <Description> element has no attribute.

The <Description> element is defined by this schema:

   <element name="Description" type="string"/>

6.4. <Provider> 🧚

The <Provider> element may contain any element that specifies or restricts the VTS Provider of the voucher. The sub-elements it contains depend on the implementation of the VTS.

A wallet system implementation may use this information to identify and/or authenticate the VTS Provider when the VTS plug-in is registered (see Section 7 of [VTS-API]). These implementation-specific elements of the VTS can be extended using [XML-ns]. An example of such a schema definition is in Section 8 💅.

The <Provider> element has a string-type "name" attribute that specifies the name of the VTS Provider.

The <Provider> element is defined by this schema:

   <element name="Provider" type="gvl:RoleType"/>
   <complexType name="RoleType" mixed="true">
    <sequence>
     <any namespace="##any" minOccurs="0" maxOccurs="unbounded"/>
    </sequence>
    <attribute name="name" type="string"/>
   </complexType>

6.5. <Issuer> 👑

The <Issuer> element may contain any element that specifies or restricts the Issuer of the voucher.

The Issuer of the voucher is generally managed by the VTS [VTS-API]. There's no need to specify the Issuer with this element if there are no restrictions on the Issuer 🙈.

A VTS implementation may use this element to describe the authentication data and/or qualification information of the Issuer. This implementation-specific information can be extended through sub-elements using [XML-ns]. An example of such a schema definition is in Section 8.

The <Issuer> element has a string-type "name" attribute that specifies the name of the Issuer.

The <Issuer> element is defined by this schema:

   <element name="Issuer" type="gvl:RoleType"/>

The <RoleType> element type is defined in Section 6.4.

If the <Issuer> element is omitted, it MUST be interpreted that there are no restrictions on the Issuer. 🫶

6.6. <Holder> 🦋

The <Holder> element may contain any element that specifies or restricts the Holder of the voucher.

The Holder of the voucher is generally managed by the VTS [VTS-API]. There's no need to specify the Holder with this element if there are no restrictions on the Holder ✨.

A VTS implementation may use this element to describe the authentication data and/or qualification information of the Holder. This implementation-specific information can be extended through sub-elements using [XML-ns].

The <Holder> element has a string-type "name" attribute that specifies the name of the Holder.

The <Holder> element is defined by this schema:

   <element name="Holder" type="gvl:RoleType"/>

The <RoleType> element type is defined in Section 6.4.

If the <Holder> element is omitted, it MUST be interpreted that there are no restrictions on the Holder. 💖

6.7. <Collector> 🎀

The <Collector> element can hold any element that's used to specify or restrict the Collector of the voucher 💅. If there are no restrictions on the Collector, you don't need this element at all, bestie ✨.

A VTS implementation can use this element to describe the authentication data and/or qualification information of the Collector 🧚. That implementation-specific info can be extended through sub-elements using [XML-ns] 🌸.

The <Collector> element has a string-type "name" attribute that's used to specify the name of the Collector 🍓.

The <Collector> element is defined by the following schema:

<element name="Collector" type="gvl:RoleType"/>

The <RoleType> element type is defined in Section 6.4. 💜

If the <Collector> element is omitted, it MUST be interpreted that there are no restrictions on the Collector. Literally the main character move 👑

6.8. <Value> 🦋

The <Value> element can optionally hold a <Fixed> or a <Ratio> element, but not both 🫶. Those sub-elements get their own sections right below this one 🌈.

The <Value> element has a "type" attribute that's used to specify the value process type. It's there to calculate the amount paid when the vouchers get redeemed at Merchant site, etc. 💖

These are the identifiers defined for the "type" attribute 🔥:

Exchange: Items specified in the <Merchandise> element can be claimed in exchange for the voucher. If this type is selected, neither the <Ratio> nor the <Fixed> element MUST be specified. Note that this value process type has the same meaning as: <Value type="discount"><Ratio percentage="100"/></Value> 🎁
Discount: Items specified in the <Merchandise> element can be purchased at the discount price calculated by the <Ratio> or <Fixed> element. 🏷️
Monetary: Items specified in the <Merchandise> element can be purchased using the value of the voucher. (Note: if the <Merchandise> element is not specified, the voucher can be used for any purchase.) If this type is selected, the <Fixed> element MUST be specified. 💸

The <Value> element also has a "spend" attribute that's used to specify the number of vouchers to be redeemed for claiming the goods, services, or monetary value specified. For example, if "n" (>0) is specified, goods can be claimed in exchange for "n sheets of" vouchers. (Note: Multiple vouchers for the same Voucher Component must exist in this case.) If "0" is specified, it can be used repeatedly. ♻️

If the "spend" attribute or the whole element is omitted, it MUST be interpreted that "1" is specified for the "spend" attribute. 🙈

The <Value> element is defined by the following schema:

<element name="Value" type="gvl:ValueType"/>
<complexType name="ValueType">
 <sequence minOccurs="0">
  <choice>
   <element name="Ratio" type="gvl:RatioValueType"/>
   <element name="Fixed" type="gvl:FixedValueType"/>
  </choice>
 </sequence>
 <attribute name="type" type="gvl:ValueProcessType"
            use="required"/>
 <attribute name="spend" type="nonNegativeInteger"
            default="1"/>
</complexType>

The <ValueProcessType> element type is defined by the following schema:

<simpleType name="ValueProcessType">
 <restriction base="string">
  <enumeration value="exchange"/>
  <enumeration value="discount"/>
  <enumeration value="monetary"/>
 </restriction>
</simpleType>

6.8.1. <Ratio> 💅

The <Ratio> element does not contain any contents. 🫧

The <Ratio> element has a "percentage" attribute that's used to specify the discount ratio of the price of the corresponding merchandize in percentage. 🍑

The <RatioValueType> element type is defined by the following schema:

<complexType name="RatioValueType">
 <attribute name="percentage" use="required">
  <simpleType>
   <restriction base="float">
    <maxInclusive value="100"/>
   </restriction>
  </simpleType>
 </attribute>
</complexType>

6.8.2. <Fixed> 💰

The <Fixed> element does not contain any contents. 🫧

The <Fixed> element has "currency" and "amount" attributes and optionally a "decimalPower" attribute, as follows:

Currency: Provides the unit of the monetary value in the three letter ISO currency code [ISO4217]. For example, US dollars is "USD". 🇺🇸
Amount: Provides the amount of the monetary value per voucher. 🪙
DecimalPower: Provides the number of decimal digits from the decimal point applied to the base for the "amount" attribute above. If the "decimalPower" attribute is omitted, it MUST be interpreted that "0" is specified for the "decimalPower" attribute. 🧮

For example, with a dollar currency denominated in cents, "1" is specified for the "amount" attribute, and "-2" is specified for the "decimalPower" attribute. Alternately, "0.01" is specified for the "amount" attribute, and the "decimalPower" attribute is omitted. Both work, iykyk 🤓

The <FixedValueType> type is defined follows:

<complexType name="FixedValueType">
 <attribute name="currency" type="string" use="required"/>
 <attribute name="amount" type="float" use="required"/>
 <attribute name="decimalPower" type="short" default="0"/>
</complexType>

6.9. <Merchandise> 🛍️

The <Merchandise> element may contain any element used to specify or restrict the goods or services rendered when the voucher is redeemed. The sub-elements in this element depend on the application of the voucher and are left to the other domain-specific specifications. Domain-specific elements can be extended as sub-elements using [XML-ns] 🌷.

This element is meant to be interpreted by a collecting system 🤖. An implementation of a wallet system does not have to use this element. Any restrictions applied should also be described in the <Description> element or the <Conditions> elements in natural language form, so users can check the restrictions 👀.

The <Merchandise> element does not have any attribute. 🫶

The <Merchandise> element is defined by the following schema:

<element name="Merchandise" type="gvl:MerchandiseType"/>
<complexType name="MerchandiseType" mixed="true">
 <sequence>
  <any namespace="##any" minOccurs="0" maxOccurs="unbounded"/>
 </sequence>
</complexType>

6.10. <ValidPeriod> 📅

The <ValidPeriod> element does not contain any contents. 🫧

The <ValidPeriod> element has dateTime-type "start" and "end" attributes that are used to place limits on the validity of the voucher. ⏳

The <ValidPeriod> element is defined by the following schema:

<element name="ValidPeriod" type="gvl:ValidPeriodType"/>
<complexType name="ValidPeriodType">
  <attribute name="start" type="dateTime"/>
  <attribute name="end" type="dateTime"/>
</complexType>

If the "start" attribute is omitted, it MUST be interpreted that the voucher is valid on any date up to that specified by the end attribute (inclusive). If the "end" attribute is omitted, it MUST be interpreted that the voucher is valid from the start attribute with no expiry. If neither attribute is specified or the whole element is omitted, it MUST be interpreted that the voucher is valid at any time. Forever and ever, periodt 💖

6.11. <Conditions> 📜

The <Conditions> element contains any other restrictions or conditions applied. It's intended to cover contracts between the issuer and the holder of the voucher in natural language form 🤝.

An implementation of a wallet system SHOULD provide a means of displaying the text in this element. Please make it visible, it's giving transparency 🪟.

The <Conditions> element has no attribute. 🫧

The <Conditions> element is defined by the following schema:

<element name="Conditions" type="string"/>

7. IANA Considerations 🌈

This document uses URNs to describe XML namespaces and XML schemas conforming to a registry mechanism described in [XML-Registry]. IANA has registered two URI assignments. Two whole registrations, very organised 📋

Registration request for the vts-lang namespace:

URI: urn:ietf:params:xml:ns:vts-lang
Registrant Contact: See the "Authors' Addresses" section of this document.
XML: None. Namespace URIs do not represent an XML specification.

Registration request for the vts-lang XML schema:

URI: urn:ietf:params:xml:schema:vts-lang
Registrant Contact: See the "Authors' Addresses" section of this document.
XML:

BEGIN
<?xml version="1.0" encoding="UTF-8"?>

<schema
  targetNamespace="urn:ietf:params:xml:ns:vts-lang"
  xmlns:gvl="urn:ietf:params:xml:ns:vts-lang"
  xmlns="http://www.w3.org/2001/XMLSchema"
  elementFormDefault="qualified">

<element name="Voucher" type="gvl:VoucherType"/>
<complexType name="VoucherType">
 <sequence>
  <element ref="gvl:Title"/>
  <element ref="gvl:Description" minOccurs="0"/>
  <element ref="gvl:Provider"/>
  <element ref="gvl:Issuer" minOccurs="0"/>
  <element ref="gvl:Holder" minOccurs="0"/>
  <element ref="gvl:Collector" minOccurs="0"/>
  <element ref="gvl:Value"/>
  <element ref="gvl:Merchandise" minOccurs="0"/>
  <element ref="gvl:ValidPeriod" minOccurs="0"/>
  <element ref="gvl:Conditions"  minOccurs="0"/>
 </sequence>
</complexType>

<element name="Title" type="string"/>

<element name="Description" type="string"/>

<element name="Provider" type="gvl:RoleType"/>
<element name="Issuer"   type="gvl:RoleType"/>
<element name="Holder"   type="gvl:RoleType"/>
<element name="Collector"   type="gvl:RoleType"/>
<complexType name="RoleType" mixed="true">
 <sequence>
  <any namespace="##any" minOccurs="0" maxOccurs="unbounded"/>
 </sequence>
 <attribute name="name" type="string"/>
</complexType>
<element name="Value" type="gvl:ValueType"/>
<complexType name="ValueType">
 <sequence minOccurs="0">
  <choice>
   <element name="Ratio" type="gvl:RatioValueType"/>
   <element name="Fixed" type="gvl:FixedValueType"/>
  </choice>
 </sequence>
 <attribute name="type" type="gvl:ValueProcessType"
            use="required"/>
 <attribute name="spend" type="nonNegativeInteger"
            default="1"/>
</complexType>

<simpleType name="ValueProcessType">
 <restriction base="string">
  <enumeration value="exchange"/>
  <enumeration value="discount"/>
  <enumeration value="monetary"/>
 </restriction>
</simpleType>

<complexType name="RatioValueType">
 <attribute name="percentage" use="required">
  <simpleType>
   <restriction base="float">
    <maxInclusive value="100"/>
   </restriction>
  </simpleType>
 </attribute>
</complexType>

<complexType name="FixedValueType">
 <attribute name="currency" type="string" use="required"/>
 <attribute name="amount" type="float" use="required"/>
 <attribute name="decimalPower" type="short" default="0"/>
</complexType>

<element name="Merchandise" type="gvl:MerchandiseType"/>
<complexType name="MerchandiseType" mixed="true">
 <sequence>
  <any namespace="##any" minOccurs="0" maxOccurs="unbounded"/>
 </sequence>
</complexType>

<element name="ValidPeriod" type="gvl:ValidPeriodType"/>
<complexType name="ValidPeriodType">
  <attribute name="start" type="dateTime"/>
  <attribute name="end" type="dateTime"/>
</complexType>

<element name="Conditions" type="string"/>
</schema>
END

8. VTS Schema Example ✨

okay so here's a little example of what the schema definition for a VTS implementation looks like 💅

<?xml version="1.0"?>

<schema
 targetNamespace="http://www.example.com/vts"
 xmlns:vts="http://www.example.com/vts"
 xmlns="http://www.w3.org/2001/XMLSchema"
 elementFormDefault="qualified">

 <element name="Version" type="string"/>
 <element name="KeyInfo" type="hexBinary"/>
</schema>

so with this schema, <vts:Version> is how you specify the VTS version number, and <vts:KeyInfo> is how you specify the Issuer in the Voucher Component, as shown in Section 5 🎀🦋

9. Security Considerations 🔐

okay this part is SERIOUS bestie 😭🫶 the VTS must provide a way to prevent forgery, alteration, duplicate-redemption, reproduction of a voucher, and non-repudiation of transactions, as described in Section 3.2 of [VTS]. this will usually mean there's a unique serial number or something similar in each Voucher instance, usually sitting outside the Voucher Component. but honestly these security requirements mostly come down to the VTS plug-ins and their protocols 💜 this document assumes the VTS plug-ins are trusted and installed by some means, e.g., manually checked the same way you'd check any other download app ✨

now the Voucher Component is where the restrictions on the VTS Provider (or VTS plug-in) live, and if that info gets altered, an incorrect VTS plug-in that the issuer never accepted could end up being used 💀 then a forged voucher could get verified as if it were valid. to avoid this disaster, the Voucher Component should be stored and acquired securely, e.g., downloaded from a trusted party over a secure channel such as [TLS] or [IPSEC], or secured by the digital signature of a trusted party [XMLDSIG] 🔥

10. Acknowledgements 🌸

huge thanks to these people, listed in alphabetic order, who contributed substantially to the material here 🫶

Ian Grigg
Renato Iannella
Yoshiaki Nakajima

11. Normative References 📚

[ISO4217]      "Codes for the representation of currencies and
               funds", ISO 4217, 1995.

[RFC2119]      Bradner, S., "Key words for use in RFCs to Indicate
               Requirement Levels", BCP 14, RFC 2119, March 1997.

[URN]          Moats, R., "URN Syntax", RFC 2141, May 1997.

[URN-NS-IETF]  Moats, R., "A URN Namespace for IETF Documents", RFC
               2648, August 1999.

[XML]          "Extensible Mark Up Language (XML) 1.0 (Second
               Edition)", A W3C Recommendation,
               <http://www.w3.org/TR/REC-xml>, October 2000.

[XML-ns]       "Namespaces in XML", A W3C Recommendation,
               <http://www.w3.org/TR/REC-xml-names>, January 1999.

[XML-Registry] Mealling, M., "The IETF XML Registry", BCP 81, RFC
               3688, January 2004.

[XML-Schema-1] Thompson, H., Beech, D., Maloney, M., and N.
               Mendelsohn, "XML Schema Part 1: Structures W3C
               Recommendation.", <http://www.w3.org/TR/xmlschema-1/>,
               May 2001.

[XML-Schema-2] Biron, P. and A. Malhotra, "XML Schema Part 2:
               Datatypes W3C Recommendation.",
               <http://www.w3.org/TR/xmlschema-2/>, May 2001.

12. Informative References 🧚

these ones are just for extra reading, bestie 📖✨

[VTS]          Fujimura, K. and D. Eastlake, "Requirements and Design
               for Voucher Trading System (VTS)", RFC 3506, March
               2003.

[IPSEC]        Thayer, R., Doraswamy, N., and R. Glenn, "IP Security
               Document Roadmap", RFC 2411, November 1998.

[TLS]          Dierks, T. and C. Allen, "The TLS Protocol Version
               1.0", RFC 2246, January 1999.

[VTS-API]      Terada, M. and K. Fujimura, "Voucher Trading System
               Application Programming Interface (VTS-API)", RFC
               4154, September 2005.

[XMLDSIG]      Eastlake 3rd, D., Reagle, J., and D. Solo,
               "(Extensible Markup Language) XML-Signature Syntax and
               Processing", RFC 3275, March 2002.

Authors' Addresses 💌

Ko Fujimura
NTT Corporation
1-1 Hikari-no-oka, Yokosuka-shi, Kanagawa, 239-0847 JAPAN

Phone: +81-(0)46-859-3053
Fax:   +81-(0)46-855-1730
EMail: fujimura.ko@lab.ntt.co.jp


Masayuki Terada
NTT DoCoMo, Inc.
3-5 Hikari-no-oka, Yokosuka-shi, Kanagawa, 239-8536 JAPAN

Phone: +81-(0)46-840-3809
Fax:   +81-(0)46-840-3705
EMail: te@rex.yrp.nttdocomo.co.jp


Donald E. Eastlake 3rd
Motorola Laboratories
155 Beaver Street
Milford, MA 01757 USA

Phone: 1-508-786-7554 (work)
       1-508-634-2066 (home)
EMail: Donald.Eastlake@motorola.com

this document is subject to the rights, licenses and restrictions in BCP 78, and except as set out there, the authors keep all their rights 💜

this document and the info in it are provided on an "AS IS" basis, and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Intellectual Property 🦋

the IETF doesn't take any position on whether any Intellectual Property Rights or other rights that might be claimed to cover the tech in this document are valid or in scope, or on whether any license under those rights might be available. it also doesn't claim to have made any independent effort to find such rights 🤷‍♀️ info on how rights work for RFC documents is in BCP 78 and BCP 79.

copies of IPR disclosures sent to the IETF Secretariat, any assurances of licenses that will be made available, and the results of any attempt to get a general license or permission for implementers or users of this spec to use those proprietary rights can be found in the IETF's online IPR repository at http://www.ietf.org/ipr.

the IETF invites anyone interested to flag any copyrights, patents, patent applications, or other proprietary rights that might cover technology needed to implement this standard. send that info to the IETF at ietf-ipr@ietf.org 💌

Acknowledgement 🌈

Funding for the RFC Editor function is currently provided by the Internet Society. 🎀✨

📦 where this page comes from

ietf: rfc4153 2005-09
💖 girlified by claude-haiku-5-5 on 2026-10-16: a language model's rewrite of the original, under its terms