Skip to content

Commit

Permalink
Merge pull request #341 from boudicca-events/TW/semantic_keys_extension
Browse files Browse the repository at this point in the history 
extend semantic keys and improve documentation
  • Loading branch information
@twatzl
twatzl authored Mar 27, 2024
2 parents 2393093 + f1918c5 commit 11684ce
Show file tree
Hide file tree
Showing 3 changed files with 85 additions and 19 deletions.
85 changes: 70 additions & 15 deletions SEMANTIC_CONVENTIONS.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,42 +22,97 @@ We use certain data types for the properties we expect.
* `list<?>`: A list of elements, the `?` describes the type of the elements in the list. Currently, elements in a list
are seperated by a newline, but this will probably change sometime
* `enum<?>`: Has to be one of the specified distinct values
* Note: publishers have to be able to handle also a value that was not specified
* `boolean`: The text "true" or "false"

### General Properties

**Events have only two required properties: `name` and `startDate`**

| Key | Meaning | Format |
|---------------------|------------------------------------------------------------------------------------------------------|--------------------------------------|
| name | The name of the event | text |
| startDate | Time of start for the event | date |
| endDate | Time of end for the event | date |
| url | A link to the website for this event | url |
| type | The type of event, for example `concert`, `????` more examples please | text ??? maybe enum would be better? |
| category | The category of an event, for example `MUSIC`, `ART` or `TECH`, see EventCategory enum | enum\<EventCategory> |
| description | Text describing this event | text |
| tags | A list of tags. TODO how to describe? | list\<text> |
| registration | If this is a free event, a event which requires registration or a event which requires a paid ticket | enum\<Registration> |
| pictureUrl | Url to a picture to be shown | url |
| collectorName | Name of the collector which collected this event | text |
| sources | A list of all sources, line by line. This should include all URLs or other sources used. | list\<text> |
| Key | Meaning | Format | Usage |
|-------------------------------|---------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------|-------------|
| name | The name of the event | text | MANDATORY |
| startDate | Time of start for the event | date | MANDATORY |
| endDate | Time of end for the event | date | OPTIONAL |
| url | A link to the specific source page for this event. If the user wants to see more details about the event, he should find them here | url | RECOMMENDED |
| type | The type of event, for example `concert`, `????` more examples please | text ??? maybe enum would be better? | RECOMMENDED |
| category | The category of an event, for example `MUSIC`, `ART` or `TECH`, see EventCategory enum | enum\<EventCategory> | RECOMMENDED |
| description | Text describing this event | text | RECOMMENDED |
| description.markdown | Text describing this event, but formatted with markdown. | text | OPTIONAL |
| recurrence.type | Describing how often an event happens. Once, rarely or very often. | enum\<RecurrenceType> | RECOMMENDED |
| recurrence.interval | Describing the interval with which the event recurs | text | OPTIONAL |
| tags | A list of tags. TODO how to describe? | list\<text> | RECOMMENDED |
| registration | If this is a free event, a event which requires registration or a event which requires a paid ticket | enum\<Registration> | OPTIONAL |
| pictureUrl | Url to a picture to be shown | url | RECOMMENDED |
| pictureAltText | Alt text for the picture | text | RECOMMENDED |
| pictureCopyright | Copyright attribution to be shown | text | OPTIONAL |
| collectorName | Name of the collector which collected this event | text | OPTIONAL |
| sources | A list of all sources that were used to gather info for this event, line by line. This should include all URLs or other sources used. | list\<text> | RECOMMENDED |
| additionalEventsFromSourceUrl | an url to page on the event source website where other events can be found (e.g. Termine or Veranstaltungen pages) (if available) | url | OPTIONAL |

#### Usage explanation

`MANDATORY`: This field is required for proper operation of boudicca.
`RECOMMENDED`: This field is not required, but it is one of the core features enabling event sorting and filtering for
publishers.
`OPTIONAL`: This field can be used if the information is available.
`DEPRECATED`: This field should no longer be used.
| recurrence.type | Describing how often an event happens. Once, rarely or very often. | enum\<RecurrenceType> |
| recurrence.interval | Describing the interval with which the event recurs | text |

#### Registration enum values

* `free`: a free event which neither requires registration nor a ticket
* `registration`: an event which requires a free registration
* `pre-sales-only`: an event which can only be entered when buying a ticket in advance
* `ticket`: a paid event which requires a ticket

#### type

type is an open field, so any value is permitted, but this is a list of common/known types:

- concert
- theatre
- meetup
- museum
- museum_railway
- model_railway
- guided_tour
- workshop
- ...

#### Category enum values

* `MUSIC`: concerts or other events where the main focus is music
* `TECH`: event with technology as the focus
* `ART`: art exhibitions, comedy, theater, ...
* `SPORT`: everything to do with sports, either watching them or actively participate

#### RecurrenceType enum values

* `REGULARLY`: events that happen about once a week or more often over the period of multiple months
* `RARELY`: events that occur about once a month throughout the year
* `ONCE`: events that occur once a year or more rarely (e.g. Christmas/Easter specials). When the same event is repeated
e.g. 3 times (for example so that more people can register), but only once a year, it should still be tagged as ONCE.

Examples:

* There is a special event with oldtimers on a museum railway that takes 2 days, but only happens once per year.
* should be tagged as ONCE
* There is a special event with oldtimers on a museum railway that takes 2 days, but only happens once per year.
* should be tagged as ONCE
* during Summer from June to September every Thursday there is a special train
* should be tagged as REGULARLY
* a specific meetup happens about once per month or every two months
* should be tagged as RARELY

#### tags values

tags is an open field, so any value is permitted, but this is a list of common/known tags:

- ...
- TODO

### Location Properties

| Key | Meaning | Format |
Expand Down Expand Up @@ -106,4 +161,4 @@ Examples:
### Internal Properties

The property name prefix `internal.*` is reserved by Boudicca for internal properties needed and will be silently
discarded if sent by an EventCollector.
discarded if sent by an EventCollector.
17 changes: 14 additions & 3 deletions boudicca.base/semantic-conventions/src/main/kotlin/base/boudicca/SemanticKeys.kt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,13 +9,18 @@ object SemanticKeys {
const val TYPE = "type"
const val CATEGORY = "category"
const val DESCRIPTION = "description"
const val RECURRENCE_TYPE = "recurrence.type"
const val RECURRENCE_INTERVAL = "recurrence.interval"
const val TAGS = "tags"
const val REGISTRATION = "registration"
const val PICTUREURL = "pictureUrl"
const val PICTURE_URL = "pictureUrl"
@Deprecated("use PICTURE_URL instead")
const val PICTUREURL = PICTURE_URL
const val PICTURE_ALT_TEXT = "pictureAltText"
const val PICTURE_COPYRIGHT = "pictureCopyright"
const val COLLECTORNAME = "collectorName"
const val SOURCES = "sources"
const val RECURRENCE_TYPE = "recurrence.type"
const val RECURRENCE_INTERVAL = "recurrence.interval"
const val ADDITIONAL_EVENTS_URL = "additionalEventsFromSourceUrl"

// location properties
const val LOCATION_NAME = "location.name"
Expand All @@ -34,4 +39,10 @@ object SemanticKeys {
// concert properties
const val CONCERT_GENRE = "concert.genre"
const val CONCERT_BANDLIST = "concert.bandlist"

object Image {
const val URL = "url"
const val ALT_TEXT = "altText"
const val COPYRIGHT = "copyright"
}
}
2 changes: 1 addition & 1 deletion buildSrc/src/main/kotlin/boudicca-openapi-generate-client.gradle.kts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ tasks.register<GenerateTask>("generateTypescriptClient") {
templateDir.set(project.rootDir.resolve("typescript_generator_overrides").path)
configOptions.putAll(
mapOf(
"npmName" to "@boudicca/search-api-client",
"npmName" to "@boudicca/${openApiPackageName}",
"npmVersion" to "${project.version}",
"supportsES6" to "true",
)
Expand Down

0 comments on commit 11684ce

Please sign in to comment.