Home » NOVA Common » NOVA Common Data Types

NOVA Common Data Types (Package ch.voev.nova.common.datatypes)

Types / Enumerations:


Types

ArtifactInfo


Properties / Associations

Name Type Multiplicity Constraints Description
name String 1..1
groupID String 0..1
artifactID String 0..1
versionInfo VersionInfo 1..1


CompositeDebugInfo

Type can be used a a container for debug info objects, also recursively.


Type Details Details
Parent Class DebugInfo


Properties / Associations

Name Type Multiplicity Constraints Description
details DebugInfo 0..* Loist with all debug info objects that are aggregated by this object.


CountryCode

Data type represents an ISO 3166 alpha-2 country code. These codes always consist of two capital letters like "CH" or "FR"


Properties / Associations

Name Type Multiplicity Constraints Description
code String 1..1 @Size(min=2, max=2)
 ISO 3166 alpha-2 country code. These codes always consist of two capital letters like "CH" or "FR".


DatePeriod

Type defines a temporal period using dates. The period that is defined by this class includes the start end and date.


Properties / Associations

Name Type Multiplicity Constraints Description
from java.time.LocalDate 1..1 Start date when the period begins. Start is included within the period.
through java.time.LocalDate 1..1 Date when the period ends. The end is included within the period.


DateTimePeriod

Type defines a temporal period using date times. The period that is defined by this class includes the start but not the end date time.


Properties / Associations

Name Type Multiplicity Constraints Description
from java.time.OffsetDateTime 1..1 Start date time when the period begins. Start is included within the period.
until java.time.OffsetDateTime 1..1 Date time when the period ends. The end is not included within the period.


DebugInfo

Type represents debug information that can be added to objects (if they support it).


Type Details Details
Abstract true


Properties / Associations

Name Type Multiplicity Constraints Description
type String 1..1


DecimalNumber

Unfortunately, OpenAPI 3.x does not support decimal values that require a higher precision (like BigDecimal e.g. in Java). Thus we have to define that type on our own here.

Similar to other implementations we work here with an unscaled value and a scale. This means that a DecimalNumber with unscaledValue = 47110815 and scale = 4 represents the decimal number "4711.0815".


Properties / Associations

Name Type Multiplicity Constraints Description
unscaledValue long 1..1 Unscaled value as part of our decimal number.
scale int 1..1 Scale part of the decimal value.


DomainExtension

Type is the base class for all domain specific extensions.

Domain extension is a generic mechanism on NOVA side that allows to add domain specific extensions in an API without introducing matching dependencies. Initially this mechanism was designed for the generic checkout process of NOVA. However, as it is not checkout specific it might also be used in other areas.


Type Details Details
Abstract true


Properties / Associations

Name Type Multiplicity Constraints Description
domainExtensionType DomainExtensionType 1..1


Duration

Type represents a duration.


Properties / Associations

Name Type Multiplicity Constraints Description
value int 1..1 @PositiveOrZero
 Length of the duration using the set time unit.
unit TimeUnit 1..1 Time unit in which the duration is defined.


ExternalReferenceID

Type is intended to be used when ever there should be the possibility that NOVA Clients can pass an external reference to requests.

One case where this is usually needed is that clients can easily map responses to requests.

From a NOVA perspective there are no constraints to this reference ID besides its maximum length. It is not expected that it is unique or anything like that.


Properties / Associations

Name Type Multiplicity Constraints Description
id String 1..1 @Size(min=0, max=64)


GeoPosition

Type describes a geo position using WGS84 coordinates.


Properties / Associations

Name Type Multiplicity Constraints Description
longitude java.math.BigDecimal 1..1 @Min(minValue=-180)
@Max(maxValue=180)
 Longitude from Greenwich Meridian. -180 (West) to +180 (East).
latitude java.math.BigDecimal 1..1 @Min(minValue=-90)
@Max(maxValue=90)
 Latitude from equator. -90 (South) to +90 (North).


IdempotencyHeader

Type is intended to be used as parameter for all NOVA REST operations that require idempotency.


Properties / Associations

Name Type Multiplicity Constraints Description
idempotencyKey IdempotencyKey 1..1 Idempotency keys are used to ensure that the same request is executed only once. It's in the responsibility of the NOVA client that an idempotency key is unique within the scope of the client. Idempotency will only be checked per operation and is not ensured for multiple calls to different methods / resources.

For further details please also check NOVA's definition about idempotency: https://confluence.sbb.ch/display/NOVA/NOVA+REST+API+Guidelines#NOVARESTAPIGuidelines-Idempotency


IdempotencyKey

Idempotency keys are used to ensure that the same request is executed only once. It's in the responsibility of the NOVA client that an idempotency key is unique within the scope of the client. Idempotency will only be checked per operation and is not ensured for multiple calls to different methods / resources.

For further details please also check NOVA's definition about idempotency: https://confluence.sbb.ch/display/NOVA/NOVA+REST+API+Guidelines#NOVARESTAPIGuidelines-Idempotency


Properties / Associations

Name Type Multiplicity Constraints Description
key String 1..1


LanguageCode

Data type represents an ISO-639-1 language code.


Properties / Associations

Name Type Multiplicity Constraints Description
code String 1..1 @Size(min=1, max=2)
 ISO-639-1 language code e.g. "de" for German.

Can be "*" when used in the NOVAContext header, to indicate that all languages should be included in the response.


LocalTimePeriod

Type defines a temporal period using local times. The period that is defined by this class includes the start but not the end time.


Properties / Associations

Name Type Multiplicity Constraints Description
from java.time.LocalTime 1..1 Start time when the period begins. Start is included within the period.
until java.time.LocalTime 1..1 Time when the period ends. The end is not included within the period.


LocalizedMarkupText

Type is used to define a localized text with one specific markup.


Properties / Associations

Name Type Multiplicity Constraints Description
markupType MarkupType 1..1 Markup type which is used to format the text.
text LocalizedString 1..1 Localized variants of the formatted text.


LocalizedString

Type defines a so called localized string. Localized string whenever a language dependent strings are needed to be used e.g. for names of products. Localized strings always have a default text and might have localizations in addition.

In general NOVA supports the languages German, French, Italian and English. However it is not guaranteed that localized string always have localizations for all those languages.


Properties / Associations

Name Type Multiplicity Constraints Description
defaultText String 1..1 @NotEmpty
@Size(min=0, max=4000)
 Default text that should be used when ever no matching localization is available.
localizations TextLocalization 0..* List with all localizations that are available for this localized string.


LocalizedURL


Properties / Associations

Name Type Multiplicity Constraints Description
defaultURL URL 1..1
localizations URLLocalization 0..*


MoneyAmount

Type represents an amount of money as it is used for prices. This class internally represents a money amount in its currency subunit.

Please be aware of the following things: * This type is not intended to be used for money amounts that require a high precision (e.g. NOVA revenues), due to limitations of OpenAPI in defining the precision of decimal numbers.


Properties / Associations

Name Type Multiplicity Constraints Description
unscaledAmount int 1..1 Unscaled amount of money using the defined currency subunit of its currency.

Example: 32.10 CHF will have an unscaledAmount of 3210 centime (aka Rappen)
currency Currency 1..1 Currency of the money amount.


MultiMarkupText

Type is used to define a localized text with several markups.


Properties / Associations

Name Type Multiplicity Constraints Description
localizedMarkupTexts LocalizedMarkupText 1..* List with all variants of the localized markup texts.


NOVAClientCode

Data type represents the code of a NOVA client e.g. "46" for SBB Mobile App. A NOVA client can be a channel as well as another systems that does not sell tickets.


Properties / Associations

Name Type Multiplicity Constraints Description
code Integer 1..1 @Max(maxValue=99999)
@Positive
 NOVA channel code like "46" for SBB Mobile App.


NOVAContext

Class represents a generic context for request to NOVA. It contains context information that are present for any kind of requests to NOVA.

The class may be extended to add additional information for specific services.


Properties / Associations

Name Type Multiplicity Constraints Description
traceParent String 0..1 The traceparent header describes the position of the incoming request in its trace graph in a portable, fixed-length format. Its design focuses on fast parsing. Every tracing tool MUST properly set traceparent even when it only relies on vendor-specific information in tracestate (see W3C Trace Context, https://www.w3.org/TR/trace-context).
traceState String 0..1 The tracestate extends traceparent with vendor-specific data represented by a set of name/value pairs. Storing information in tracestate is optional (see W3C Trace Context).
conversationID String 0..1 Conversation id is used to group together a sequence of REST calls to NOVA. All requests that belong to the same business process are supposed to have the same conversation id.
acceptLanguage LanguageCode 0..1 Preferred language of the requesting client. Attribute can be filled according to logic of HTTP Header field as defined on Accept-Language. This explicitly includes weighting of languages (e.g. "fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5").

However please be aware that NOVA in general only supports the languages "de", "fr", "it" and "en".

Even though the parameter is optional it's strongly recommended to provide it in requests, if not default language will be used. Please be aware that NOVA's default language is not explicitly defined and may change over time without prior notice.
dateShift String 0..1 Header field can be used to modify the date part of the request time stamp. It can either be defined as an absolute date in format "YYYY-MM-DD" or as an relative shift using '+' / '-' in combination with a shift value as absolute number for the amount of days that should be shifted (e.g. "-7" or "+2" days).

Date shift is only supported on non productive environments.
timeShift String 0..1 Header field can be used to modify the time part of the request time stamp. It can either be defined as an absolute time in format HH:mm:ss or as an relative shift using '+' / '-' in combination with a shift value as absolute number for the amount of minutes that should be shifted (e.g. "-31" or "+120" minutes).

Time shift is only supported on non productive environments.
organizationCode OrganizationCode 0..1 Identification for the organization (aka as LV or Leistungsvermittler in most cases in NOVA 14) that sends a request.

In the future, this information will be resolved from the authorization token. This means that NOVA will overwrite the value of this header if it was provided by a client.
novaClientCode NOVAClientCode 0..1 Identification of the NOVA client that sends a request (aka Kanal / Channel in NOVA 14).

In the future, this information will be resolved from the authorization token. This means that NOVA will overwrite the value of this header if it was provided by a client.
novaSubject String 0..1 Identification of the NOVA subject (=primary TKID) that sends a request.

This header allows to artificially restrict the current request, for tokens that would otherwise have unrestricted access to all NOVA subjects.
For most token types, this information will be resolved from the authorization token (from the nova_sub claim) and this header is ignored.

This header is only supported on non productive environments.
enableDebugInfo boolean 1..1 Header field can be used to enable debug info in responses on request level. Using the header additional debug info will be returned as part of NOVA responses.

Depending on the environment and other criteria it might happen that even though this header is set, no debug info will be returned. The reason for that is that producing debug info is a very expensive / chatty thing and might overload the application if it is used too intensively.
clientApiVersion String 0..1 The NOVA API version of the REST client / user agent sending the request.
Endpoints of the NOVA platform may use this to adjust their behavior (ex. relax validation, warn about deprecated versions, ..).

Since 3.3.0. Will become mandatory in 4.0.0.


ObjectChangeLogEntry

Generic type to build a change log for a business object.


Properties / Associations

Name Type Multiplicity Constraints Description
objectID I 1..1 ID of the object whose changes are described by this log entry.
data D 1..1 Business data (payload) describing the changes of the object from a business perspective.
eventTimestamp java.time.OffsetDateTime 1..1 Timestamp when the change log entry was created. This might not be the same point in time when the change becomes active from a business perspective.
effectiveChangeTimestamp java.time.OffsetDateTime 1..1 Timestamp when the represented object
effectiveState S 1..1 Effective state of the object. The object has this state at effectiveChangeTimestamp.
event T 1..1 Event that triggered the change of the object.
actor UserReferenceID 1..1 Actor that caused the change of the object.
clientInfo C 1..1 Additional info about the NOVA client through which the object change was caused.


ObjectIDDebugInfo

Class can be used to use debug info about an object with an unique ID.


Type Details Details
Parent Class DebugInfo


Properties / Associations

Name Type Multiplicity Constraints Description
name String 1..1 Name of the property about which the debug info is.
objectID String 1..1 ID of the object about which the debug info is.


Pageable

Generic type for all NOVA responses that support paging.


Properties / Associations

Name Type Multiplicity Constraints Description
page int 1..1 Index of the page that was be returned.
size int 1..1 Size of the page that was returned. This value shows the requested page size. It might happen that in reality less objects are returned. In this case property hasMore will be false.
hasMore boolean 1..1 Attribute is set to "true" in case that there are more pages with data available.
objects T 0..*


PagingParams

Type can be used by REST operations that want to offer paging of their responses.


Properties / Associations

Name Type Multiplicity Constraints Description
page int 0..1 Index of the page that should be returned. First index starts with 0.
size int 0..1 Size of the page that should be returned.


PlainPropertyDebugInfo

Type can be used as debug info for a single property.


Type Details Details
Parent Class DebugInfo


Properties / Associations

Name Type Multiplicity Constraints Description
name String 1..1 Name of the property about which the debug info is.
value String 1..1 Debug info value for the property.


RawDomainExtension


Type Details Details
Parent Class DomainExtension


Properties / Associations

Name Type Multiplicity Constraints Description
rawValue String 1..1


TextLocalization

Objects of this type represent one concrete localization of a string.


Properties / Associations

Name Type Multiplicity Constraints Description
text String 1..1 @NotEmpty
@Size(min=0, max=4000)
 String using the defined language.
language LanguageCode 1..1 Language in which the text of this object is.


TimePeriod

Type defines a temporal period using times. The period that is defined by this class includes the start but not the end time.


Properties / Associations

Name Type Multiplicity Constraints Description
from java.time.OffsetTime 1..1 Start time when the period begins. Start is included within the period.
until java.time.OffsetTime 1..1 Time when the period ends. The end is not included within the period.


URL


Properties / Associations

Name Type Multiplicity Constraints Description
url String 1..1 @NotBlank
@Size(min=0, max=2048)


URLLocalization


Properties / Associations

Name Type Multiplicity Constraints Description
url URL 1..1
language LanguageCode 1..1


UserReferenceID

Type is used to represent information about a user without actually storing any data that is GDPR relevant. A user can be a customer as well as a sales agent.

In any case the user information is taken from the authentication token of the NOVA request.


Properties / Associations

Name Type Multiplicity Constraints Description
id String 1..1 @Size(min=0, max=512)
 Reference ID representing the user. What is taken as ID depends on the IdP that was used to identify a user.


VersionInfo

Type describes a version of an artifact (API, application etc.)


Properties / Associations

Name Type Multiplicity Constraints Description
version String 1..1 Version number of the artifact.


VersionLabel

Type can be used to provide version information about an object e.g. to avoid dirty writes (aka optimistic locking) or to detect outdated data.

Important: - This type is not connected at all with versioning of NOVA Master Data


Properties / Associations

Name Type Multiplicity Constraints Description
version int 1..1 @PositiveOrZero



Enumerations

ChannelType

Enumeration describes the different types of channel that are distinguished by NOVA.

Literals

Name Description
ONLINE Channels like mobile apps or web shops.
TICKET_VENDING_MACHINE Any kind of ticket vending machines.
TICKET_COUNTER Server point of sale can be an agent at a station or a bus driver.
BATCH Channel that operates in a batch mode.
POST_PRICING Channel that operates in post pricing mode. (currently not used)

Currency

Enumeration defines all the currencies that are known in the NOVA ecosystem. Please be aware that in this list also EUR is present even though it is supported only in very rare cases.

Literals

Name Description
CHF Swiss Francs is currently the one and only currency that is supported by NOVA.
EUR Currently currency EUR is not supported by NOVA. This literal is only present to avoid breaking changes in the future, but most likely EUR will never be supported.
This is also the reason why this literal is marked as deprecated.

DateTimeRestriction

Enumeration can be used to express constraints concerning dates, date times or times.

Literals

Name Description
FUTURE
FUTURE_OR_PRESENT
PAST
PAST_OR_PRESENT

DomainExtensionType

Enumeration defines all domain extensions that are available on NOVA.

Please be aware that this type is a so called extensible enum. This means that additional literals might be added in the future and that this is considered to be a non-breaking / SemVer compliant change.

Literals

Name Description
MOCK Literal for mock domain extension. This extension is only used for test purposes.
COUPON Literal for coupon domain extension.
RAW Literal for raw representation of a domain extension. This literal is only used for technical reasons and must not be referenced in business code.
QUOTA Literal for quota domain extension.
INVENTORY Literal for inventory domain extension.
PUBLIC_TRANSPORT Literal for public transport domain extension.
SWISSPASS Literal for SwissPass domain extension.
CUSTOMER Literal for customer domain extension.
PARKING Literal for parking domain extension.
PARKING_PROMO_CODE Literal for P+Rail promo code domain extension.
PARKING_VAUD_QUOTA_SERVICE Literal for domain extension for parking quota service of canton of Vaud.
ZONE_RESTRICTION_CHECK Literal for domain extension that is used for zone restriction check.
UNKNOWN Please be aware that this enum is an extensible enum. This means that new literals can be introduced without prior notice.

MarkupType

Enumeration defines the possible markup types that can be used in fulfillments.

Please be aware that this type is a so called extensible enum. This means that additional literals might be added in the future and that this is considered to be a non-breaking / SemVer compliant change.

Literals

Name Description
PLAIN_TEXT
MARKDOWN
HTML
UNKNOWN Please be aware that this enum is an extensible enum. This means that new literals can be introduced without prior notice.

MaturityLevel

Enumeration defines the maturity levels that are used for NOVA APIs.

Literals

Name Description
UNKNOWN Please be aware that this enum is an extensible enum. This means that new literals can be introduced without prior notice.

TimeUnit

Enumeration represents time units.

Literals

Name Description
MINUTES
HOURS
DAYS
WEEKS
MONTHS
YEARS

Weekday

Enum defines all days of a week.

Literals

Name Description
MONDAY
TUESDAY
WEDNESDAY
THURSDAY
FRIDAY
SATURDAY
SUNDAY