|
Network Holiday Protocol Ver. 0.3.0
1. 概要 2. 出力形式 3. カントリーコード 4. 日付 5. リクエスト 6. データフォーマット 7. 返り値 8. HL拡張 9. ユーザ拡張 10. データベースの更新 11. NHPサーバの同期に関する草案 12. ロードマップ 1. 概要 ネットワークホリデープロトコル（以下、NHP）は、指定した期間または指定日に存在する国単位の祝日データを返す。NHPは、祝日の不規則性を回避することがその最大かつ唯一の目的であり、複雑な処理・操作はクライアント側で行うべきという原則に基づいて設計される。 祝日の定義は各国の法律または慣習による。一例として、日本国の場合は、「国民の祝日に関する法律」による祝日と皇室慶弔行事に伴う休日、および臨時に制定される国の公休日を国の祝日とする。 このヴァージョンは、0.3.0であり、2016-03-30に改定された。 2. 出力形式 データはCSVファイルとして出力される。祝日名に","が含まれる場合は、","は"%2C"に変換される。祝日名に"%2C"を含む場合は、URLエスケープによる変換に準拠する。また、祝日名に改行が含まれることは想定されていない。 文字コードはUTF-8、改行は、<CR><LF>である。 3. カントリーコード カントリーコードは、ISO 3166-1に準拠し、数値による指定は必須、その他での指定への対応は推奨される。デフォルトカントリーは各NHPサーバの任意である。 4. 日付 日付は、西暦と月日の8桁、それに時分の4桁を加えた12桁、またはさらに秒の二桁を加えた14桁の数値によって表され、西暦4桁、月日時分秒はそれぞれ二桁が使われ、それぞれ一桁の場合は0詰めされる。0で開始する4桁の西暦は不正値として扱われる。5桁の西暦は未来を表すものではなく、不正値として扱われる。よって、仕様上、サポートする期間は1000-01-01~9999-12-31であるが、各NHPサーバが対応すべき期間は、当日より前後1年が必須であり、1970年以降の祝日データを参照できることが推奨される。また、対応期間は連続した一つの期間である。この日付の仕様については9900年に改定・調整が行われる予定である。 5. リクエスト NHPサーバを利用するクライアントは、以下の6種のリクエストを用いる。何も指定されなかった場合は、status=1が指定されたものとみなす。 start 祝日データを参照する最初の日を指定する。8桁の数値のみで西暦月日を表す。詳細は日付の項を参照。endが指定されなかった場合は、データベースの有効期間終了日が指定されたものとする。 end 祝日データを参照する最後の日を指定する。8桁の数値のみで西暦月日を表す。詳細は日付の項を参照。startが指定されなかった場合は、データベースの有効期間開始日が指定されたものとする。 day 祝日データを参照する日を指定する。8桁の数値のみで西暦月日を表す。詳細は日付の項を参照。同時にstartまたはendが指定された場合、startおよびendは無視される。 country 祝日を参照する国をISO 3166-1に準拠するコードで指定する。指定されなかった場合は各NHPサーバの任意のデフォルトカントリーが選択される。 level リクエストレベルを指定する。詳細はHL拡張を参照。デフォルトは、0（各NHPサーバ任意のデフォルト）である。 order 祝日データの列記順を指定する。デフォルトは、1である。 0 - 不定 1 - 昇順（上方ほど新） 2 - 降順（下方ほど新） status 0 - 何もしない。その他のリクエストに影響を与えない。 1 - サーバのスタイタス情報を出力して終了する。その他のリクエストは無視する。 2 - すべての祝日データを出力する。その他のリクエストは無視する。 3 - 祝日データを更新する。その他のリクエストは無視する。 4 - Ver. 0.2を使用する（HL拡張を用いない）。 5~15 - リザーブ 16~31 - ユーザ拡張用リザーブ 6. データフォーマット 返されるデータは、行頭に"#"を持つステイタス部とそれ以降の祝日データ部に分かれる。ステイタス部の一行目、二行目は必須、三行目以降は拡張用である。データは","で区切られる。 ex. #0,201603022057,0.3.0,JPN,1,start=20170501&end=20170831 #1,20150101,20180228,201603012342,201602170206,1,http://nhp.example.jp/nhp.cgi ##administrator mail address, nhp@nhp.exmaple.jp 20170811,山の日,1 20170717,海の日,1 20170505,こどもの日,1 20170504,みどりの日,1 20170503,憲法記念日,1一行目第一項（ex.における0）は返り値で、返り値を参照。 同第二項（ex.における201603022057）はこのデータの取得日時を12桁の数値で表したものである。 同第三項（ex.における0.3.0）はNHPのヴァージョンである。 同第四項（ex.におけるJPN）はカントリーコードで、ISO 3166-1に準拠するコードで示す。 同第五項（ex.における1）はリクエストレベルで、HL拡張を参照。デフォルトは、NHPサーバの任意である。 同第六項（ex.におけるstart=20170501&end=20170831）はクライアントリクエストで、NHPサーバが受け取ったリクエストである。nhp on httpの場合、環境変数QUERY_STRINGと同値である。 二行目第一項（ex.における1）はデータ順で、祝日データの列記順である。0=不定、1=昇順（上方ほど新）、2=降順（下方ほど新）デフォルトは、1である。 同第二項（ex.における20150101）は有効期間開始日で、祝日データを参照可能な最初の日である。 同第三項（ex.における20180228）は有効期間終了日で、祝日データを参照可能な最後の日である。 同第四項（ex.における201603012342）は祝日データ更新日時で、そのNHPサーバが祝日データを更新した日時である。ただし、ルートサーバにおいては常に更新されているものとみなす。 同第五項（ex.における201602170206）はオリジナルデータ更新日時で、そのNHPサーバが参照しているオリジナルの祝日データの更新日時である。 同第六項（ex.における1）は参照レベルで、そのNHPサーバの祝日データがいくつのNHPサーバを経由したかを示している。 同第七項（http://nhp.example.jp/nhp.cgi）は参照URLで、そのNHPサーバが祝日データを参照しているNHPサーバのURLである。 三行目以降において#COUNTRY,で始まる行は、そのNHPサーバが対応しているすべての国の国コードを","で区切って並記し、改行で終了する。この項目は、status=1のリクエストでは必須の表示項目であるが、それ以外では任意である。 三行目以降において#DEFAULT_REQUEST_LEVEL,で始まる行は、そのNHPサーバのデフォルトリクエストレベルを示し、改行で終了する。この項目は、status=1のリクエストでは必須の表示項目であるが、それ以外では任意である。 三行目以降において#NHP_SERVER_URL,で始まる行は、そのNHPサーバのURLを示し、改行で終了する。この項目は、status=1のリクエストでは必須の表示項目であるが、それ以外では任意である。 ##で開始する行はコメント行であり、なくとも良いが、付加する場合は三行目以降に挿入する。コメント行はステイタス部と連続しているか、またはステイタス部に内包されていなければならない。なお、コメントは祝日データには含まれない。よって、削除または変更しても祝日データの修正とはみなされない。 データ部は、「日付,祝日名,データレベル値」が改行で終了し、列記される。データレベル値とは、その祝日が属するホリデーレベルのホリデーレベル値の合計である。詳細はHL拡張を参照。 指定した期間、または指定日に祝日が存在しない場合、祝日データは何も返されない。 7. 返り値 0 … 成功 1 … サーバ設定不備 2 … 祝日データ未設定 4 … ネットワークエラー 8 … ファイルパーミッションエラー 16 … その他のエラー 100 … 不正リクエスト +1 - start,end,day,country,level,order,status以外のリクエストを含んでいる +2 - 端末からのみ実行できる操作を端末以外から実行している 200 … 不正値のリクエスト +1 - データベースより以前のデータを要求 +2 - データベースより未来のデータを要求 +4 - start > end +8 - 不正な日付、または有効範囲外の値 +16 - 想定外の文字種を含んでいる、または未入力 +32 - 対応していないカントリーコード 400 … statusリクエストに関するエラー +1 - 未実装なステイタスリクエスト +2 - 祝日データ取得エラー +64 … 必須有効期間未対応 8. HL拡張 HL拡張の目的は、地方公共団体、会社、学校などの独自の休日に国の祝日とは各別にまたは同時に対応することである。現在(Ver. 0.3.0)の拡張では、祝日はそれぞれのホリデーレベルに属し、そのレベル値を持ち、NHPサーバは要求されたリクエストレベル（要求された各ホリデーレベルのレベル値の合計）に合致する祝日を返す。 各ホリデーレベル名の一覧は、ステイタス部の三行目以降に含まれる"#HL"を行頭に持つ行で、","で分割、並記される。ホリデーレベルは右端に向かって1から1づつ増加し、改行で終了する。ホリデーレベル=1は国の祝日として固定であり、それに相応しいホリデーレベル名を設定しなければならない。 各ホリデーレベルのホリデーレベル値は、2LevelNumber-1となり、クライアントは要求するホリデーレベルのホリデーレベル値の合計値をリクエストレベルとしてlevelで指定する。この仕様は実装を規定するものではないが、HL拡張はいわゆるビットマスクにより実装・運用されることが想定されている。下記はリクエストレベル=(1+8)=9の一例である。 #HL,国民の祝日,県民の日,市政公休日,学校 20160811,山の日,1 20160718,海の日,1 20160622,創立記念日,8 20160505,こどもの日,1 HL拡張は拡張が宣言されていなくても（ホリデーレベル名の一覧が省略されていても）有効である。この場合、ホリデーレベル名「Country」、ホリデーレベル=1のみが設定されたものとみなす。 クライアントのリクエストレベルでlevel=0が指定された場合、もしくは何も指定されなかった場合は各サーバーのデフォルトリクエストレベルを指定したものとみなす。デフォルトリクエストレベルは各サーバーの任意であるが、デフォルトリクエストレベルでは対応国の国の祝日のみを返すことが推奨される。ただし、クライアントが限定・周知している環境においてはこの限りではない。また、level=1が指定された場合は、対応国の国の祝日のみを返さねばならない。 祝日は、複数のホリデーレベルに属することができる。この場合、属するホリデーレベルのホリデーレベル値を合計した値が祝日データのデータレベル値となる。 データレベル値=0は平日である。平日はデータベース上にデータレベル値=0として存在することがあるが、Ver. 0.3.0ではクライアントが直接参照する方法はない。 ホリデーレベル名は祝日データである。よって、新設、改廃した場合には祝日データに修正を加えたものとみなす。 データレベルが未設定の祝日は、ホリデーレベル=1（国の祝日）とみなす。これは、Ver. 0.2との互換性を考慮したものであり、Ver. 0.4以降では正しいデータレベルを持たない祝日は不正値とみなす予定である。 9. ユーザー拡張 ステイタス部の三行目以降にはユーザー独自のデータを含ませることができる。この場合、行頭の#に拡張名を続け、","で区切り、以降、任意のデータを記述し、改行で終了する。ただし、ユーザー拡張の拡張名は"X"で開始する。 ex. #X_CGI_VERSION,0.2.16 10. データベースの更新 NHPサーバは上位のNHPサーバの祝日データに同期して、その祝日データを更新することができる。ただし、status=3による更新は管理者のみが実行できるよう強く推奨される。 データの更新は、参照するNHPサーバにstatus=2のリクエストを行い、対象国のすべての祝日データを取得することによって行うことを想定している。 データの更新にあたり、祝日データにそのNHPサーバ独自の修正を加えた場合、参照レベルは0(NHPルートサーバ)になる。ホリデーレベル名の変更も祝日データの修正とみなす。##COMMENTは祝日データではないので、削除または修正しても参照レベルに影響を与えない。 11. NHPサーバの同期に関する草案 NHPは階層化・分散化したシステムを指向しており、そのための同期プロトコルが提案されている。この草案は、nhp.cgi-0.2以降で実装されている。 NHP同期プロトコル草案 12. ロードマップ NHPの今後の予定は以下の通りである。 2016 … 0.3.0公開 2017 … 同期プロトコル草案公開 2019 … 0.3.0の修正版として0.3.1を策定 2021 … 同期プロトコル草案を仕様に含む0.4.0を策定 2022 … 0.4.0の修正版として0.4.1を策定 2024 … 1.0.0のRC版である0.9.0を策定 2026 … 1.0.0を策定 |