vCardのURLにバックスラッシュが残る理由 エスケープとCRLF
連絡先を QR コードや .vcf ファイルで渡す vCard は、1行に「名前:値」を並べただけの単純な形式に見える。ところが値の中にカンマやセミコロンが入ると、書き方とパーサーの組み合わせで結果が変わる。
この記事では、ハシトシステムの 連絡先QRコード生成 と CSV→vCard(.vcf)変換 が出力する vCard 3.0 を例に、次の3点を確かめる。
- URL の値にもエスケープをかけると、バックスラッシュが残るパーサーがある
- JavaScript で
'\;'と書いたエスケープは、セミコロンをエスケープしていない - 改行が LF だけだと読めないパーサーがある
検証環境は Windows 11、Node.js v24.11.1(ical.js 2.2.1、vcf 2.1.2)、Python 3.11.9(vobject 0.9.9)である。
vCard 3.0 のエスケープ規則
vCard 3.0 は RFC 2426(1998年)、その土台の書式は RFC 2425 で決められている。値の型によってエスケープの扱いが違うのが要点である。
| プロパティ | RFC 2426 での値の型 | エスケープ |
|---|---|---|
FN NOTE TITLE など |
text | \\ \; \, \n を使う |
N ADR ORG |
構造化された text(; で区切る) |
区切りでない ; は \; にする |
URL |
uri | text のエスケープは定義されていない |
text の文法は RFC 2426 の付録で次のように書かれている。
1 | |
一方 URL は「A single uri value」とされ、text ではない。URI の中のカンマやセミコロンは RFC 3986 で使ってよい文字なので、そのまま書くのが本来の形である。
ORG が構造化されている点も重要である。RFC 2426 の ORG は「組織名;部署1;部署2」のように ; で階層を区切る。会社名そのものに ; が入っていてエスケープされていないと、2つ目以降は部署名として読まれる。
vCard 4.0(RFC 6350、2011年)では 3.4 節で、N や ADR のような複合プロパティの中の ; は必ずエスケープ、そうでないプロパティでは「エスケープしてもよい(MAY)」と整理された。
改行についても RFC 2425 と RFC 2426 の文法は、各行を CRLF で終えると決めている。
2つのツールの出力
2026-11-18 に本番の HTML を取得し、エスケープ関数を取り出して Node.js で動かした。
| 入力 | 連絡先QRコード生成 | CSV→vCard変換 |
|---|---|---|
Hashito;R&D |
Hashito\;R&D |
Hashito;R&D |
Hashito, Inc. |
Hashito\, Inc. |
Hashito\, Inc. |
https://example.com/?q=a,b;c(URL 欄) |
https://example.com/?q=a\,b\;c |
https://example.com/?q=a\,b;c |
| 行の区切り | LF | CRLF |
CSV→vCard変換の関数には「カンマ・セミコロン・バックスラッシュ・改行をエスケープする」というコメントがあり、コードは次のとおりである。
1 | |
3行目だけ '\\;' でなく '\;' になっている。JavaScript の文字列リテラルで \; は特別な意味を持たない文字のエスケープとして扱われ、ただの ; になる。つまり ; を ; に置き換えているだけで、何もしていない。strict モードでもエラーにならないので気付きにくい。
1 | |
3つのパーサーで読む
同じ vCard 3.0 を、エスケープと改行を変えて ical.js・vcf・vobject に読ませた。ORG は Hashito;R&D、NOTE は 月;水 在席、URL は https://example.com/?q=a,b;c を入れたつもりのデータである。
| ケース | ical.js 2.2.1 | vcf 2.1.2 | vobject 0.9.9 |
|---|---|---|---|
| A: 全部エスケープ・LF | ORG 正しい / URL に \ が残る |
エラー | ORG・URL とも正しい |
| B: 全部エスケープ・CRLF | ORG 正しい / URL に \ が残る |
値をそのまま返す | (A と同じ) |
C: '\;' の書き間違い・CRLF |
ORG が Hashito と R&D に分かれる |
値をそのまま返す | ORG が Hashito と R&D に分かれる |
D: URL は %2C %3B・CRLF |
すべて正しい | 値をそのまま返す | すべて正しい |
分かったことは次のとおりである。
- URL のエスケープ: ical.js は URL を uri 型として扱い、
\,を戻さない。結果はhttps://example.com/?q=a\,b\;cで、このままブラウザに渡すとクエリが変わる。vobject は URL も text と同じように戻すのでa,b;cになる。パーサーによって答えが分かれる書き方は避けたほうがよい '\;'の書き間違い:ORGは構造化された値なので、ical.js も vobject もHashitoを組織名、R&Dを部署名として読む。NOTEは構造化されていないので、エスケープが無くても月;水 在席のまま読めた- ical.js の NOTE: エスケープした
月\;水 在席が、ical.js では\を残したまま返った。ORGの\;は正しく戻しているので、構造化されていない text の\;だけ戻さない動きである。RFC 6350 では構造化されていないプロパティの;のエスケープは任意なので、NOTEでは;をエスケープしないほうが、どのパーサーでも同じ結果になる - LF だけの改行: vcf は
Unsupported version "ARD"というエラーで読めなかった。ical.js と vobject は LF でも読めた - vcf の値: vcf 2.1.2 の
valueOf()はエスケープを戻さず、ファイル上の文字列をそのまま返す。使う側で戻す必要がある
URL にカンマやセミコロンを入れたいときは、D のようにパーセントエンコード(, は %2C、; は %3B)にすると、エスケープの解釈に関係なく全パーサーで同じ文字列になる。ただし %2C と , はサーバーによって別の値として扱われることもあるので、もとの URL が動くかは確かめる。
ツールの修正点
確かめた結果、次の点を修正対象として記録した。
- CSV→vCard変換:
.replace(/;/g, '\;')を.replace(/;/g, '\\;')に直す。会社名や氏名に;が入ると、ORGやNの区切りがずれる - 2つのツールとも:
URLに text のエスケープをかけない。カンマやセミコロンを含む URL は、そのまま書くかパーセントエンコードにする - 連絡先QRコード生成: 行の区切りを LF から CRLF にする。RFC の文法どおりにし、厳しいパーサーでも読めるようにする
QR コードに入れたときに読み取り側のスマートフォンがどう扱うかは、今回は確かめていない。ここでの結果は上記のライブラリでの実測である。
同じように1行に「名前:値」を並べる iCalendar の折り返しとエスケープは、ICSの75オクテット折り返しで日本語が化ける理由とセミコロンの書き忘れ で調べている。
実際に試す
前提: Node.js(確認は v24.11.1)と Python 3(確認は 3.11.9)。空のディレクトリで実行する。
まず Node.js で、ical.js と vcf に同じ vCard を読ませるスクリプトである。
1 | |
1 | |
出力は JSON.stringify なので、\\ は実際の値では \ 1つである。C の ical.js の org が二重の配列になっているのは、組織名と部署名の2つに分かれたことを表している。
次に Python の vobject で同じデータを読む。
1 | |
1 | |
Windows のコンソールで日本語が化けるときは、先に set PYTHONIOENCODING=utf-8(PowerShell なら $env:PYTHONIOENCODING='utf-8')を実行する。
vCard を書き出すときの注意
- text の値(
FNNOTEなど)と構造化された値(NADRORG)は、\;,改行をエスケープする。\を最初に置き換える - JavaScript で置換後の文字列を書くときは
'\\;'と2つ重ねる。'\;'は;そのものになる URLには text のエスケープをかけない。カンマやセミコロンが入る URL は、パーセントエンコードにすると解釈の違いが出ない- 行は
CRLFで区切る。LF だけだと読めないパーサーがある - 書き出したファイルは、少なくとも2種類のパーサーで読み戻して確かめる
まとめ
- vCard 3.0(RFC 2426)では、text の値にだけ
\;\,のエスケープが定義され、URLは uri 型である。 URLにエスケープをかけると、ical.js 2.2.1 ではバックスラッシュが残り、vobject 0.9.9 では戻る。パーサーで答えが分かれる。- JavaScript の
'\;'は;と同じで、セミコロンをエスケープしたつもりでも何も変わらない。構造化されたORGでは組織名が2つに分かれた。 - 改行が LF だけの vCard は、vcf 2.1.2 ではエラーになった。
- ハシトシステムの2つの vCard ツールには、これらに当たる箇所があり、修正対象として記録した。
結果は 2026-11-18 時点の上記の環境とツールの実装で得たものである。
参考
- RFC 2426「vCard MIME Directory Profile」(1998年9月)3.5.5 ORG、3.6.8 URL、4. Formal Grammar の text-value と ESCAPED-CHAR
- RFC 2425「A MIME Content-Type for Directory Information」(1998年9月)5.8.1 Line delimiting and folding(行の区切りは CRLF)
- RFC 6350「vCard Format Specification」(2011年8月)3.4 Property Value Escaping、6.7.8 URL
- ical.js 2.2.1、vcf 2.1.2、vobject 0.9.9 での上記スクリプトによる実測
- ハシトシステム 連絡先QRコード生成・CSV→vCard(.vcf)変換の本番 HTML(2026-11-18 取得)
このバージョンはその範囲に入るのか
依存の話でいちばん間違えやすいのは ^1.2.3 や ~1.2.3 がどこまでを許すかです(^0.2.3 のようにメジャーが 0 のときは規則が変わります)。範囲とバージョンを貼ると、下限・上限に展開したうえで一致・不一致とその理由を表示するsemver 範囲判定ツールを置いています。ブラウザの中だけで動き、入力はどこにも送信しません。