Entityの形式は以下の通りです。
|
{
"id": <Enttyのid>,
"type": "<Entity type>,
<Attribute>,
<Attribute>,
・・・・
} |
: idとtypeは必須です。
|
<Attribute>の形式は以下の通りです。この形式をNormalized形式と呼びます。
|
<Attribute名>: {
"type": "<Attribute type>,
"value": <Attribute value>,
"metadata": {
<Metadata名: {
"type": <Metadatatype>,
"value": <Metadatavalue>
}
}
} |
: Attribute名に"id"と"type"は使えません
: valueは必須です。
: 座標の値の時は、"value"の代わりに"coordinates"を使います
: metadataは無くても構いません |
typeとmetadataは省略可能です。typeを省略すると、Valueの記述によりデフォルトタイプが割り当てられます。デフォルトタイプとは、Boolean, Text, Number、およびStructuredValueの事です。
<attribute>は、keyValue形式でも表現できます。但し、keyValue形式を使う際にはoptions=keyValuesを指定する必要があります。
keyValue形式は、以下の通りです。
|
<Attribute名>: <Attribute value> |
この様に<Attribute>をkeyValue形式に省略できるのは、以下の場合です。
- "type"が"Text"、"Number"、"Boolean"、"Array"、"StructuredValue"、および"geo:json"の場合は、<Attribute value>を見ればtypeが分かるので、keyValue形式に出来ます
- Metadataは表現出来ません。GET時にはMetadataは返却されません
2022-09-20/2023-11-21
次節以降で、id、type、各種名称などで他と識別するための名前「識別子」が出てきます。ここでは、それらの識別子に共通な定義をします。
識別子は、以下の連続した文字から構成される、1文字から256文字までの文字列です。
|
半角英数字, "-", ".", "_", "~" |
尚、NGSI V2の仕様では、識別子には制御文字、空白、"&"、"?"、"/"、"#"以外の全てのASCII文字を使える仕様になっています。本書では、以下の理由で禁止文字を追加しています。
- "@": NGSI V2 の後継であるNGSI-LD で"@"は特別な意味を持つキーワードとなっているため、互換上の問題を避ける意味から利用可能な文字の種類から外しました
- """", "$", "%", "*", ",", "{", "}", "[", "]": JSON で特別な意味を持っていたり、更新演算子と勘違いしたりするので、混乱を避ける意味から利用可能な文字の種類から外しました
- "'", "\": 環境によって動作が異なる可能性があり、混乱する可能性があるので利用可能な文字の種類から外しました
- "=": URL 中に記述すると特別な意味を持ち、セキュリティ上の問題を発生させる可能性のある文字を外しました。NGSI V2 仕様では、「利用者の責任」と記載されていますが、不特定多数が参加するスマートシティでは利用者にゆだねるべきではないとの考え方です
- "<", ">", ";", "(", ")": デジタル庁で推奨モジュールとしているFiware/Orion ではサポートしてないため、除外しました
- URNで予約文字となっている文字は除外しました
2022-04-20/2023-11-21
NGSI V2の規定では、idはEntityに振られたidentifierであり、実装環境の同一Entity type内で一意と決められています。
idは、以下の二つの規則に従う必要があります。
一つ目の規則は、「識別子」であること。二つ目の規則は、以下のパターンであることです。二つ目の規定はNGSI-LDの規定なのですが、将来の移行時に問題にならない様に、今のうちらか準拠しておきます。尚、この規定になると、idは実装環境内で他のEntity type含めて一意になります。尚、コロン(":")は前項で識別子には使えないとしましたが、これはURNのデリミターとして予約語になっているためです。従って、idの記述にはコロンを記述しますが、利用者が決める部分には使用できません。
|
urn:ngsi-ld:<Entity type>:<entity-id> |
<Entity type>については、次節で説明します。<entity-id>については、一つ目の規則に従う必要があります。つまり、英数字や前記の記号以外は使えません。例えば、日本語やキリル文字、ドイツ語のウムラウトなども使えません。尚、本来Entityのidは"urn:ngsi・・"含め、以降の文字列全体を指します。fiware.orgで前記の様な表現をしていたので、そのまま踏襲して記載しましたが、正しくはidは文字列全体を指すことに留意してください。
2022-04-20
Entityが従うデータモデルの名称です。
Entity typeは、識別子の規則に加え、以下の三つの規則にも従う必要があります。
- アメリカ英語であること。
- 先頭の文字は大文字であること。複数の単語が含まれる場合は単語の間は空けることなく単語を連続してつなげる、キャメルケースとすること。
- 使おうとするEntityのデータモデルが既に定義されている場合は、既存の定義を再利用すること。
既存の定義はSmart Data Modelsやschema.orgに掲載されています。また、検討中のContextも掲載されています。これらを参照し、作りたいContextがあれば、それを再利用します。
尚、データモデルの標準化については、政府としては政府で定めるとの方針を示していますが、詳細は本日時点では把握できていません。別の機会にまとめて記載したいと思います。
既に述べたidとtypeもAttributeですが、この二つは特別な扱いをされています。idとtypeは必須であり、一度格納したら変更する事が出来ません。
|
<Attribute名>は、識別子の規則に加え、以下の規則にも従う必要があります。
- 先頭の文字が小文字のキャメルケースの形式です。例えば、streetAddress、addressRegion、addressLocality、postalCode等の様になります。
- 次の文字列は使用不可です。"id", "type", "geo:distance", "orderby", 下記のBuiltin Attributeにある文字列, "*"
- JSON-LDへの移行のため、@の使用は避けて下さい
AttributeにはBuiltin Attributesという予め構造が決められているものがあります。以下のみっつです。
- dateCreated (type : DateTime) : エンティティ作成日時の文字列です。名称はdateですが、ミリ秒まで入っています(Fiware/Orion Rev. 3.6)。
- dateModified (type : DateTime) :エンティティ変更日時の文字列です
- dateExpires (type : DateTime) : エンティティの有効期限の文字列です。尚、どの様な実装になるのかは規定されていません。
dateCreatedとdateModifiedのAttributeは定義しなくても勝手に定義されたように動作しますが、検索時には明示的にこれらのAttribute名を指定しないと返却されません。dateModifiedは、一度も更新していないのに検索しようとすると、400のエラーになります。dateExpiresは、指定しないのに検索しようとすると、400のエラーになります。
| 8.1.5 Attribute typeとAttribute value |
2022-09-24/2023-02-10
Attribute typeはAttribute valueに格納されるデータの形式を示します。
NGSI V2で定義されているデータタイプは以下の通りです。種類の項目の意味は、"D"はデフォルトデータタイプ、"S"はスペシャルデータタイプです。デフォルトデータタイプとは、Attribute typeを省略したときにvalueの形式により自動的に解釈されるデータタイプです。例えば、valueが"abc"であれば"abc"は文字列だと分かるので、データタイプはTextであると解釈されます。
| テータタイプ |
種類 |
Valueに格納する値に関する説明 |
| Boolean |
D |
論理値。JSONで定義されている。具体的には値にはTrue または Falseが入る。TrueとFalseは文字列とは別に定義されているので、ダブルクオートで囲む必要はない。. |
| DateTime |
S |
YYYY-MM-DDThh：mm：ss [Z |（+ |-）hh：mm]の形式。詳細はISO 8601の第5.4章。標準上紀元前を表すために先頭にマイナスを付加したり、YYYYを5桁以上も使用できるが、データ交換の関係者間の事前合意が必要としており、スマートシティでは実質的に使ってはいけない表現となる。YYYYは西暦。月と日は二桁の数値で表現するとともに、年月日の間には"-"を挟む。つまり米国式のApril 20th, 2022や2022/04/20は認められない。
年月日と時刻の間にはセパレーターとして"T"を挟む。hhは24時間制で表現。
秒の後の"Z"はUTC (協定世界時) であることを示す。UTC以外の場合には、Zの代わりにタイムゾーンを記載する。例えば日本の場合は"+09:00"となる。
JSON上は文字列として扱うので、ダブルクォートで囲む必要がある。
JSONの定義にはなく、JSON形式上は文字列として扱われるので、ダブルクォートで囲む必要がある。 |
| geo:box |
S |
|
| geo:json |
S |
Attributeのtypeに"gro:json"が指定された場合、そのAttributeのvalueはGeo:JSONオブジェクトであることを示す。GeoJSONオブジェクトにはPoint、 LineString、 Polygon、 MultiPoint、 MultiLineString、およびMultiPolygonの6種類がある。例えば、点の場合はValueは次の様に記述する。
{"type"="Point", "coordinates": [102.0, 0.5]}。最後の数値の並びは[東経, 北緯, 高度]であり、高度は省略しても良い。西経と南緯はそれぞれマイナス(-)の符号を数値の前に置く。 |
| geo:line |
S |
Lineのgeo:jsonである事を示します |
| geo:point |
S |
Pointのgeo:jsonである事を示します |
| geo:polygon |
S |
Ppolygonのgeo:jsonである事を示します |
| Number |
D |
0123456789の数字および最大1つのピリオドを小数点として使用する文字列。カンマを読みやすさのために使う事は避ける必要がある。標準上ピリオドの代わりにカンマを使用できる事になっており、一部の説明でカンマを優先的に使うとの記述もあるが、Schema.orgは、ピリオドを使うべきとしている。
JSONで定義されているデータタイプであり、ダブルクォートで囲む必要はない。 |
| StructuredValue |
D |
構造を持つValue。構造は、オブジェクト(波括弧{}で囲われたSub-Attribute群)か、列(大括弧[]で囲まれたValue群。筆者は現時点(2022-09-24)で、Sub-AttributeのNGSI V2規格の説明は見つかっていない。Fiware/Orionで動作確認したところ、Attributeと同様にtypeとvalueを指定する形式でも、keyValue形式同様に<Sub-Attribute名>: <Attribute value>形式でもNormalizaed形式としてPOSしてもエラーにはならない。Fiware Foundationのチャートリアルでは後者の記述となっているので、本書でも後者を採用する。尚、登録時に前者で登録したか後者で登録したかで、GET時に返却されるペイロードが異なる。前者はtypeとvalueが返却されるのに対し、後者はkryValuesの指定が無くてもSub-SttributeだけkeyValue形式で返却される。プログラミング時は両方に対応する必要がある。 |
| Text |
D |
文字列。Valueに日本語を格納しても構わない。JSONの定義にある様に、値はダブルクオートで囲む必要がある |
前記のデータタイプ以外に以下のデータタイプがよく利用されます。これらはNGSI V2で規定されているものではないため、Valueの形式によりデフォルトデータタイプとして処理されます。
| テータタイプ |
Valueに格納する値に関する説明 |
| Date |
ISO8601の5.3章で定義されている日付の形式。YYYY-MM-DD[Z |（+ |-）hh：mm]形式。標準上紀元前を表すために先頭にマイナスを付加したり、YYYYを5桁以上も使用できるが、データ交換の関係者間の事前合意が必要と規定されており、関係者を特定できないスマートシティでは実質的に使ってはいけない表現となる。YYYYは西暦。月と日は二桁の数値で表現するとともに、年月日の間には"-"を挟む。つまり米国式のApril 20th, 2022や2022/04/20は認められない。
DDの後の"Z"はUTC (協定世界時) であることを示す。UTC以外の場合には、Zの代わりにタイムゾーンを記載する。例えば日本の場合は"+09:00"となる。
処理系ではTextとして扱われるので、ダブルクォートで囲む必要がある。また、形式が不正でもエラーにならない。 |
| Float |
浮動小数点数。処理系ではNumberとして扱われるので、ダブルクォートでは囲まない。 |
| Integer |
整数。処理系ではNumberとして扱われるので、ダブルクォートでは囲まない。また、小数点以下があってもエラーとはならない |
| URL |
URLを表す文字列。"http:"や"https"も含めた文字列。一般的ではないが、定義上はユーザ名やパスワードをURLに含める事も可能だが、値として入れて良いかどうかは処理系依存の可能性がある。また、URLには日本語は記載できないので、データとして格納する場合は、エンコードして格納する必要がある。処理系ではTextとして扱われるので、ダブルクォートで囲む必要がある。 |
| Time |
ISO8601の5.3章で定義されている日付の形式。hh：mm：ss [Z |（+ |-）hh：mm]の形式。hhは24時間制で表現。
秒の後の"Z"はUTC (協定世界時) であることを示す。UTC以外の場合には、Zの代わりにタイムゾーンを記載する。例えば日本の場合は"+09:00"となる。
処理系ではTextとして扱われるので、ダブルクォートで囲む必要がある。また、形式が不正でもエラーにならない。 |
| ContactPoint |
;連絡先を示すオブジェクトを格納します。 |
| PostalAddress |
住所を示すオブジェクトを格納します。schema.orgでは分割せずTextで記述する方法も許していますが、Smart Data modelsではオブジェクトのみ許しているので、オブジェクトで記述します。 |
| Relationship |
他のEntityのidを格納して、リンクを張るための属性です。この属性は慣例的に使分けているものですが、NGSI-LDへの移行が容易になるため、リンクは必ずこの属性にします。格納するのは文字列なので、Text同様にダブクォートで囲みます。 |
2022年8月14日
Metadataはなるべく使用しない事を推奨します。これは、NGSI-LDへの移行時に障害になるためです。
Metadataを使用する場合、Metadata名は識別子の規則に従う必要があると共に、以下の規則にも従う必要があります。
- 次の文字列は使用不可です。下記のBuiltin Metadataにある文字列, "*"
typeとvalueははAttribute typeと同じです。
Attributeと同様にBuiltin Metadataというものも決められています。
- dateCreated (type: DateTime) : 属性作成日の文字列です
- dateModified (type: DateTime) : 属性変更日の文字列です
- previousValue: <値>は、Attribute valueの以前の値です。このMeatadataのtypeは、Attributeの以前のtypeです
- actionType (type: Text) : Attributeが、通知を トリガーしたリクエストに含まれていた場合に含まれます。 その値は、更新の場合は update、 作成の場合は append、削除の場合は deleteです
|
