Close
logoGovernify

iAgree Syntax 5.2

Last update: 25 days ago by JesusAparicioOrtizReading time: 4 min

Governify uses iAgree specification lenguage to model SLAs.

iAgree Specification

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Revision History

Versions tagged with R are inteded for research purpouses. Other versions are operational versions used in real projects.

VersionDateNotes
1.0R2013Initial WS-Agreement derived DSL.
2.02016Move to a new YAML independent syntax.
3.02016Changes for interoperabilty with Governify Registry.
4.0R2017Extensions for SLA4OAI.
5.02017Improved computers section.
5.12019Collector and metrics improvements
5.22021Customizable Window period
6.0R2020Changing focus from SLA-based to Customer-Agreement-based.

Version 5.2

Introduction

iAgree is an open source standard for describing Service Level Agreements (SLAs).

This SLA definition in a neutral vendor flavor will allow to foster innovation in the area. By this way, management tools can import and measure metrics and build SLAs for composed services in a standard approach.

Specification

An iAgree description is a JSON or a YAML document with following structure. Note that primitive data types in the iAgree specification are based on the types supported by the JSON-Schema Draft 4.

Class diagram

SLA Object

Each iAgree document must contain the following sections:

Field nameField typeRequired/OptionalDescription
idStringRequireddocument unique identification
versionStringRequireddocument version
typeStringRequireddocument type based on the SLA lifecycle
contextContextObjectRequiredholds the main information of the SLA context
termsTermsObjectRequiredholds the main information of the SLA terms
Example
Synthetic
id: MyServiceAgreement
version: 1.0.0
type: agreement
context: ContextObject
terms: TermsObject

ContextObject

Holds the main information of the SLA context.

Field nameField typeRequired/OptionalDescription
iAgreeStringRequirediAgree specification version
providerStringOptionaldata about the owner/host of the service
consumerStringOptionaldata about the entity that consumes the service.
validityValidityObjectOptionalholds the main information of the SLA validity
definitionsDefinitionsObjectRequiredholds the main information of the SLA definitions
infrastructureObjectRequiredprovides information about the tools used for SLA storage, calculation, governance, etc.
Example
Synthetic
context:
iAgree: 2.0
provider: ISA Research Group
consumer: Acme
validity: ValidityObject
infrastructure:
designer: 'http://designer.governify.io'
portal: 'http://portal.governify.io'
registry: 'http://registry.governify.io'
definitions: DefinitionsObject

ValidityObject

Holds the main information of the SLA validity.

Field nameField typeRequired/OptionalDescription
initialStringRequiredstart date of the SLA according to ISO 8601 time format
timeZoneStringRequiredtime zone of the SLA according to ISO 8601 time zone format
endStringOptionalend date of the SLA according to ISO 8601 time format
Example
Synthetic
validity:
initial: '2014-10-16'
timeZone: Europe/Madrid

DefinitionsObject

Holds the main information of the SLA definitions.

Field nameField typeRequired/OptionalDescription
schemasArray [Object]Requireddefinition schemas
scopesArray [Object]Requireddefinition scopes
Example
Synthetic
definitions:
schemas:
myMetric:
description: some gathered values
type: double
unit: '%'
scopes:
myGlobalScope:
myScope:
myPropertyName: myPropertyValue
SLA for API services
definitions:
schemas:
animalTypes:
type: integer
format: int64
description: Number of different animal types.
resourceInstances:
type: integer
format: int64
description: Number of pet resources
requests:
type: integer
format: int64
description: Number of requests
responseTime:
type: integer
format: int64
description: Time in ms spent by request
SLA for human services
definitions:
schemas:
escalatedIncidentPercentage:
description: Percentage of incidents escalated by first level support teams
type: double
unit: '%'
resolutionTime:
description: Immediate incident resolution by first level support teams
type: string
unit: hours
schedule:
description: service schedule
type: string

TermsObject

Holds the main information of the SLA terms.

Field nameField typeRequired/OptionalDescription
pricingPricingObjectRequiredHolds the main information of the SLA pricing.
metricsMetricsObjectRequiredHolds the main information of the SLA metric.
guaranteesArray[GuaranteeObject]RequiredHolds the main information of the SLA guarantees.
configurationsConfigurationsObjectOptionalHolds the main information of the SLA configurations.
quotasArray[QuotaObject]OptionalHolds the main information of the SLA quotas.
ratesArray[RateObject]OptionalHolds the main information of the SLA rates.
Example
Synthetic
terms:
pricing: PricingObject
metrics: MetricsObject
guarantees: Array[GuaranteeObject]
configurations: ConfigurationsObject
quotas: Array[QuotaObject]
rates: Array[RateObject]

PricingObject

Holds the main information of the SLA pricing.

Field nameField typeRequired/OptionalDescription
costDoubleOptionalcost associated to this service.
currencyStringOptionalcurrency used to express the cost according to ISO 4217. Samples: USD, EUR, or BTC for US dollar, euro, or bitcoin, respectively.
billingBillingObjectRequiredholds the main information of the SLA billing.
Example
Synthetic
pricing:
cost: 50.0
currency: EUR
billing: BillingObject

BillingObject

Holds the main information of the SLA billing.

Field nameField typeRequired/OptionalDescription
periodString: ["onepay", "daily", "weekly", "monthly", "quarterly", "yearly"]Requiredperiod used for billing. Supported values are: onepay: unique payment before start using the service; daily: billing at the end of every day; weekly: billing at the end of every week; monthly: billing at the end of every month; quarterly: billing at the end of every quarter; yearly: billing at the end of every year
initialStringOptionalstart date of the billing cycle according to ISO 8601 time format
penaltiesArray[CompensationObject]Optionalholds the main information of the SLA billing penalties
rewardsArray[CompensationObject]Optionalholds the main information of the SLA billing rewards
Example
Synthetic
billing:
period: monthly
SLA for human services
billing:
period: monthly
initial: '2016-05-12T10:35:36.000'
penalties:
- over:
escalatedIncidentPercentage:
$ref: '#/context/definitions/schemas/escalatedIncidentPercentage'
aggregatedBy: sum
groupBy:
serviceLine:
$ref: '#/context/definitions/scopes/serviceDesk/serviceLine'
activity:
$ref: '#/context/definitions/scopes/serviceDesk/activity'
upTo: -10

MetricsObject

Holds the main information of the SLA metrics.

Field nameField typeRequired/OptionalDescription
{{metridId}}MetricObjectRequiredholds the main information of a SLA single metric
Example
Synthetic
metrics:
myMetric1: MetricObject
myMetric2: MetricObject
myMetric3: MetricObject
SLA for API services
metrics:
requests: MetricObject
resourceInstances: MetricObject
animalTypes: MetricObject
SLA for human services
metrics:
issue_start: MetricObject
issue_end: MetricObject
issue_duration: MetricObject

MetricObject

Holds the main information of a SLA single metric.

Field nameField typeRequired/OptionalDescription
schemaObjectRequiredmetric schema
measureObjectRequiredmetric measure
typeStringRequiredmetric type
scopeObjectRequiredmetric scope
Example
Synthetic
myMetric1:
schema:
$ref: '#/context/definitions/schemas/myMetric'
type: consumption
scope:
myScope:
$ref: '#/context/definitions/scopes/myGlobalScope/myScope'
SLA for API services
requests:
schema:
$ref: '#/context/definitions/schemas/requests'
type: consumption
scope:
resource:
$ref: '#/context/definitions/scopes/api/resource'
operation:
$ref: '#/context/definitions/scopes/api/operation'
level:
$ref: '#/context/definitions/scopes/oai/level'
account:
$ref: '#/context/definitions/scopes/oai/account'
resourceInstances:
schema:
$ref: '#/context/definitions/schemas/resourceInstances'
type: check
scope:
resource:
$ref: '#/context/definitions/scopes/api/resource'
operation:
$ref: '#/context/definitions/scopes/api/operation'
level:
$ref: '#/context/definitions/scopes/oai/level'
account:
$ref: '#/context/definitions/scopes/oai/account'
animalTypes:
schema:
$ref: '#/context/definitions/schemas/animalTypes'
type: check
scope:
resource:
$ref: '#/context/definitions/scopes/api/resource'
operation:
$ref: '#/context/definitions/scopes/api/operation'
level:
$ref: '#/context/definitions/scopes/oai/level'
account:
$ref: '#/context/definitions/scopes/oai/account'
SLA for human services
issue_start:
schema:
description: incident start date
type: string
computer: 'http://ppinot.computer.papamoscas-company-devel.governify.io/api/v1/indicators/issue_start/'
issue_end:
schema:
description: incident end date
type: string
computer: 'http://ppinot.computer.papamoscas-company-devel.governify.io/api/v1/indicators/issue_end/'
issue_duration:
schema:
description: incident duration
type: string
unit: seconds
computer: >-
http://ppinot.computer.papamoscas-company-devel.governify.io/api/v1/indicators/issue_duration/

CompensationObject

Holds the main information of a SLA single compensation.

Field nameField typeRequired/OptionalDescription
overObjectRequiredmetrics involved in the compensation calculation process
ofArray[ScopedCompensationObject]Optionalholds the main information of the SLA scoped compensations
aggegatedByStringOptionalcompensation aggregation function
groupByObjectOptionalcompensation aggrupation function
upToDoubleOptionalcompensation limit
Example
Synthetic
penalties:
over:
myMetric:
$ref: '#/context/definitions/schemas/myMetric'
of: ScopedCompensationObject
aggregatedBy: sum
groupBy:
myScope:
$ref: '#/context/definitions/scopes/myGlobalScope/myScope'
upTo: -10
SLA for API services
penalties:
- over:
escalatedIncidentPercentage:
$ref: '#/context/definitions/schemas/escalatedIncidentPercentage'
of: ScopedCompensationObject

ScopedCompensationObject

Holds the main information of a SLA single scoped compensation.

Field nameField typeRequired/OptionalDescription
valueStringRequiredscoped compensation value
conditionStringRequiredscoped compensation condition
Example
Synthetic
- value: '-2'
condition: myMetric >= 90.00
SLA for human services
- value: '-1.5'
condition: serviceDesk_KPI_03A > 99.98 && serviceDesk_KPI_03A <= 100.00

GuaranteeObject

Holds the main information of a SLA single guarantee.

Field nameField typeRequired/OptionalDescription
idStringRequiredguarantee unique identification
descriptionStringOptionalguarantee description
scopeObjectRequiredguarantee scope
ofArray[ScopedGuaranteObject]Requiredholds the main information of the SLA scoped guarantees
Example
Synthetic
guarantees:
id: myGuarantee
scope:
myScope:
$ref: '#/context/definitions/scopes/myGlobalScope/myScope'
of: Array[ScopedGuaranteObject]
SLA for API services
guarantees:
- id: guarantees_responseTime
scope:
plan:
$ref: '#/context/definitions/scopes/offering/plan'
resource:
$ref: '#/context/definitions/scopes/api/resource'
operation:
$ref: '#/context/definitions/scopes/api/operation'
level:
$ref: '#/context/definitions/scopes/oai/level'
account:
$ref: '#/context/definitions/scopes/oai/account'
of: Array[ScopedGuaranteObject]
SLA for human services
guarantees:
- id: serviceDesk_KPI_12A
scope:
priority:
$ref: '#/context/definitions/scopes/serviceDesk/priority'
node:
$ref: '#/context/definitions/scopes/serviceDesk/node'
serviceLine:
$ref: '#/context/definitions/scopes/serviceDesk/serviceLine'
activity:
$ref: '#/context/definitions/scopes/serviceDesk/activity'
of:
Array[ScopedGuaranteObject]

ScopedGuaranteObject

Holds the main information of a SLA single scoped guarantee.

Field nameField typeRequired/OptionalDescription
scopeObjectRequiredscoped guarantee scope
objectiveStringRequiredguarantee objective
withObjectOptionaldefinition of metrics referenced in scope attribute
windowWindowObjectRequiredguarantee window
evidencesArray[Object]Optionalguarantee evidences
penaltiesArray[CompensationObject]Optionalholds the main information of the SLA guarantee penalties
rewardsArray[CompensationObject]Optionalholds the main information of the SLA guarantee rewards
Example
Synthetic
of
- scope:
myScope: P1
objective: myMetric <= 1.00
with:
myMetric: {}
window: WindowObject
evidences:
- myMetric_evidence:
$ref: '#/terms/metrics/myMetric1_evidence'
penalties: Array[CompensationObject]
SLA for API services
of:
- scope:
plan: '*'
resource: '*'
operation: '*'
level: account
account: '*'
objective: responseTime <= 800
window: WindowObject
- scope:
plan: pro
resource: '*'
operation: '*'
level: account
account: '*'
objective: responseTime <= 250
window: WindowObject
SLA for human services
- scope:
priority: P1
node: '*'
objective: serviceDesk_KPI_12A >= 95.00
with:
serviceDesk_KPI_12A:
resolutionTime: <= 2
schedule: 'L-DT00:00-23:59'
window: WindowObject
evidences:
- issue_start:
$ref: '#/terms/metrics/issue_start'
- issue_end:
$ref: '#/terms/metrics/issue_end'
- issue_duration:
$ref: '#/terms/metrics/issue_duration'
penalties: Array[CompensationObject]

WindowObject

Holds the main information of the SLA guarantee window.

Field nameField typeRequired/OptionalDescription
initialStringOptionalstart date of the window according to ISO 8601 time
endStringOptionalend date of the window according to ISO 8601 time
rulesStringOptionalrules of the window according to Rrule library following the iCalendar RFC specification, with a few important differences. Two rules must be defined, the first one for the start of the periods and the second one for the end, separated by "---"
typeStringRequiredwindow type
periodString: ["hourly", "daily", "weekly", "monthly", "yearly", "customRules"]Requiredused period. Supported values are: hourly: at the end of every hour; daily: at the end of every day; weekly: at the end of every week; monthly: at the end of every month; yearly: at the end of every year; customRules: defined in 'rules' field
Example
Monthly period with an initial date of '2009-10-16'
window:
initial: '2009-10-16'
type: static
period: 'monthly'
Custom period. The first rule is defined for the periods start every day at 10 o'clock and the second one is defined for the periods end every day at 22 o'clock.
window:
type: static
period: 'customRules'
rules: 'DTSTART:20200101T000000Z\nRRULE:FREQ=DAILY;INTERVAL=1;BYHOUR=10---DTSTART:20200101T000000Z\nRRULE:FREQ=DAILY;INTERVAL=1;BYHOUR=22'

You can find more documentation of the period definition here.

ConfigurationsObject

Holds the main information of the SLA configurations.

Field nameField typeRequired/OptionalDescription
{{configurationId}}ConfigurationObjectRequiredholds the main information of the SLA configurations
Example
Synthetic
configurations:
myConfiguration1: ConfigurationObject
myConfiguration2: ConfigurationObject
myConfiguration3: ConfigurationObject
SLA for API services
configurations:
availability: ConfigurationObject

ConfigurationObject

Holds the main information of a SLA single configuration.

Field nameField typeRequired/OptionalDescription
scopeObjectRequiredconfiguration scope
ofArray[ScopedConfigurationObject]Requiredholds the main information of the SLA scoped configuration
Example
Synthetic
myConfiguration1:
scope:
myScope:
$ref: '#/context/definitions/scopes/myGlobalScope/myScope'
of: ScopedConfigurationObject
SLA for API services
availability:
scope:
plan:
$ref: '#/context/definitions/scopes/offering/plan'
of: ScopedConfigurationObject

ScopedConfigurationObject

Holds the main information of a SLA singled scoped configuration.

Field nameField typeRequired/OptionalDescription
scopeObjectRequiredconfiguration scope
value{String, Number, Boolean}Requiredconfiguration value
Example
Synthetic
of:
- scope:
myScope: '*'
value: 'true'
SLA for API services
of:
- scope:
plan: '*'
value: 'R/00:00:00Z/15:00:00Z'
- scope:
plan: pro
value: 'R/00:00:00Z/23:59:59Z'

QuotaObject

Holds the main information of a SLA single quota.

Field nameField typeRequired/OptionalDescription
idStringRequiredquota unique identification
scopeObjectRequiredquota scope
overObjectRequiredmetrics involved in the quota calculation process
ofArray[ScopedQuotaObject]Requiredholds the main information of the SLA scoped quotas.
Example
Synthetic
- id: myQuota
scope:
myScope:
$ref: '#/context/definitions/scopes/myGlobalScope/myScope'
over:
myMetric:
$ref: '#/terms/metrics/myMetric1'
of: Array[ScopedQuotaObject]
SLA for API services
- id: quotas_requests
scope:
plan:
$ref: '#/context/definitions/scopes/offering/plan'
resource:
$ref: '#/context/definitions/scopes/api/resource'
operation:
$ref: '#/context/definitions/scopes/api/operation'
level:
$ref: '#/context/definitions/scopes/oai/level'
account:
$ref: '#/context/definitions/scopes/oai/account'
over:
requests:
$ref: '#/terms/metrics/requests'
of: Array[ScopedQuotaObject]

ScopedQuotaObject

Holds the main information of a SLA single scoped rate.

Field nameField typeRequired/OptionalDescription
scopeObjectRequiredscoped quota scope
limitsArray[LimitObject]Requiredholds the main information of a SLA scoped quota limit
Example
Synthetic
- scope:
myScope:
$ref: '#/context/definitions/scopes/myGlobalScope/myScope'
limits: Array[LimitObject]
SLA for API services
- scope:
plan: '*'
resource: /pets
operation: get
level: tenant
account:
$ref: '#/context/consumer'
limits:
- max: 40
period: hourly
- scope:
plan: pro
resource: /pets
operation: post
level: account
account: '*'
limits:
- max: 100
period: minutely

LimitObject

Holds the main information of a SLA scoped quota/rate limit.

Field nameField typeRequired/OptionalDescription
maxNumberRequiredquota/rate maximum value
periodString: ["daily", "weekly", "monthly", "quarterly", "yearly"]Optionalused period. Supported values are: daily: at the end of every day; weekly: at the end of every week; monthly: at the end of every month; quarterly: at the end of every quarter; yearly: at the end of every year
Example
Synthetic
limits:
- max: 40
period: hourly

RateObject

Holds the main information of a SLA single rate.

Field nameField typeRequired/OptionalDescription
idStringRequiredrate unique identification
scopeObjectRequiredrate scope
overObjectRequiredmetrics involved in the rate calculation process
ofArray[ScopedRateObject]Requiredholds the main information of the SLA scoped rates.
Example
Synthetic
rates:
- id: myRate
scope:
myScope:
$ref: '#/context/definitions/scopes/myGlobalScope/myScope'
over:
myMetric:
$ref: '#/terms/metrics/myMetric1'
of: Array[ScopedRateObject]
SLA for API services
rates:
- id: rates_requests
scope:
plan:
$ref: '#/context/definitions/scopes/offering/plan'
resource:
$ref: '#/context/definitions/scopes/api/resource'
operation:
$ref: '#/context/definitions/scopes/api/operation'
level:
$ref: '#/context/definitions/scopes/oai/level'
account:
$ref: '#/context/definitions/scopes/oai/account'
over:
requests:
$ref: '#/terms/metrics/requests'
of: Array[ScopedRateObject]

ScopedRateObject

Holds the main information of a SLA single scoped rate.

Field nameField typeRequired/OptionalDescription
scopeObjectRequiredscoped rate scope
limitsArray[LimitObject]Requiredholds the main information of a SLA scoped rate limit
Example
Synthetic
- scope:
myScope:
$ref: '#/context/definitions/scopes/myGlobalScope/myScope'
limits: Array[LimitObject]
SLA for API services
- scope:
plan: '*'
resource: /pets
operation: get
level: account
account: '*'
limits:
- max: 3
period: secondly
- scope:
plan: free
resource: /pets
operation: get
level: account
account: '*'
limits:
- max: 1
period: secondly

Examples

  • A basic and synthetic example, in YAML and JSON format, compliant with the current iAgree specification version.
  • A SLA for an API service, in YAML and JSON format, which defines some pricing plans and quotas/rates over "pets" resources.
  • A SLA for a human service, in YAML and JSON format, that tries to regulate some metrics and guantees in a "IT service desk" process.

References

  1. Keywords to indicate requirement levels - RFC 2119.
  2. JSON
  3. YAML
  4. Date and time encoding - ISO 8601
  5. Currency codes - ISO 4217
Previous
Collector Events
Next — 📑 Reference Guides
Infrastructure