-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathimplementation-notes.html
407 lines (332 loc) · 16.7 KB
/
implementation-notes.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
<!DOCTYPE html>
<!--
Copyright (C) 2019 by John Cardinal.
Everyone is permitted to copy and distribute verbatim copies of this document, but changing it is not allowed.
-->
<html lang="en">
<head>
<meta charset="utf-8" />
<title>GEDCOM 5.5.2 Implementation Notes</title>
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" href="styles.css" />
<link rel="alternate stylesheet" href="light.css" title="Light" />
<link rel="stylesheet" href="dark.css" title="Dark" />
</head>
<body id="top">
<article>
<header>
<h1>GEDCOM 5.5.2 Implementation Notes</h1>
</header>
<div>
<dl>
<dt class="editor">Editor:</dt>
<dd class="editor p-author">John Cardinal (<span class="organization"><a class="external" href="https://www.familyhistoryhosting.com">Family History Hosting, LLC</a></span>)</dd>
</dl>
</div>
<div id="copyright-notice">
<p>Copyright © 2019 by John Cardinal</p>
<p>Everyone is permitted to copy and distribute verbatim copies of this document, but changing it is not allowed.</p>
</div>
<section>
<h2>Contents</h2>
<ul class="toc-list">
<!-- Table of Contents entries -->
<li class="toc-0"><a href="#section-document-information">Document Information</a></li>
<li class="toc-1"><a href="#abstract">Abstract</a></li>
<li class="toc-1"><a href="#document-status">Document Status</a></li>
<li class="toc-0"><a href="#section-introduction">Introduction</a></li>
<li class="toc-0"><a href="#section-system-changes">System Changes</a></li>
</ul>
</section>
<section id="section-document-information">
<h2>Document Information</h2>
<h3 id="abstract">Abstract</h3>
<p>This document provides GEDCOM 5.5.2 implementation advice intended for software authors.</p>
<h3 id="document-status">Document Status</h3>
<p>This document is a <em>Draft</em>. Feedback and comments are welcome. You may create a pull-request to propose and collaborate on changes to the document. A future version of this document will remove its <em>Draft</em> status.</p>
<dl class="simple-list">
<dt>GitHub Project</dt>
<dd><a href="https://github.com/jfcardinal/GEDCOM-5.5.2">GEDCOM-5.5.2</a></dd>
<dt>Public URL of Document</dt>
<dd><a href="https://jfcardinal.github.io/GEDCOM-5.5.2/implementation-notes.html">https://jfcardinal.github.io/GEDCOM-5.5.2/implementation-notes.html</a></dd>
<dt>Associated documents</dt>
<dd><a href="https://jfcardinal.github.io/GEDCOM-5.5.2/index.html">https://jfcardinal.github.io/GEDCOM-5.5.2</a></dd>
</dl>
</section>
<section id="section-introduction">
<h2>Introduction</h2>
<p>The <a class="external" href="gedcom-5.5.2.html">GEDCOM 5.5.2 specification</a> is a minor revision to GEDCOM 5.5.1. For software authors, there are relatively few changes to implement, which was an explicit goal for GEDCOM 5.5.2.</p>
<p>GEDCOM <em>readers</em> that import GEDCOM 5.5.1 documents using UTF-8 encoding should require few changes. Most full-featured programs already handle common exceptions to GEDCOM 5.5 and GEDCOM 5.5.1, such as reasonable field values that exceed the GEDCOM length restriction but are valid in GEDCOM 5.5.2.</p>
<p>GEDCOM <em>writers</em> that export GEDCOM 5.5.1 documents using UTF-8 encoding should also require few changes to export GEDCOM 5.5.2 documents. However, it is vital that GEDCOM writers that export GEDCOM 5.5.2 documents follow the GEDCOM 5.5.2 specifications completely.</p>
</section>
<section id="section-changes">
<h2>System Changes</h2>
<dl>
<dt id="character-encoding-change">UTF-8</dt>
<dd>
<p>GEDCOM 5.5.2 specifies only a single valid character encoding: <strong>UTF-8</strong>.</p>
<h4>Full Support</h4>
<p>Most modern GEDCOM-processing systems support UTF-8, and for those systems, supporting this requirement will be tactical:</p>
<ul>
<li>
<strong>GEDCOM Readers</strong>
<ul>
<li>Verify that GEDCOM 5.5.2 documents (A) are encoded with UTF-8 and (B) specify UTF-8 on the HEAD.CHAR subrecord. Reject documents that do not meet those two requirements.</li>
</ul>
</li>
<li>
<strong>GEDCOM Writers</strong>
<ul>
<li>Restrict output encoding to UTF-8 when writing GEDCOM 5.5.2 documents. Do not allow users to chose another output encoding when writing GEDCOM 5.5.2 documents.</li>
<li>Write the UTF-8 Byte Order Mark prefix (U+00EF, U+00BB, U+00BF) as the first bytes in the document.</li>
</ul>
</li>
</ul>
<h4>Limited Support</h4>
<p>Systems that can read documents encoded with UTF-8 but do not support Unicode internally should be capable of limited support for GEDCOM 5.5.2:</p>
<ul>
<li>
<strong>GEDCOM Readers</strong>
<ul>
<li>Decode the UTF-8 text to the encoding used internally in the program. If the input document contains characters that cannot be represented accurately in the encoding used internally:
<ol>
<li>Write an error message for each affected subrecord so the end user is aware of each decoding failure.</li>
<li>Convert the character(s) that cannot be decoded accurately to a character or character sequence that enables the end user to locate the incorrect text.</li>
</ol>
</ul>
</li>
</ul>
<p>Systems that can write documents encoded with UTF-8 but do not support Unicode internally should be capable of full support for GEDCOM 5.5.2:</p>
<ul>
<li>
<strong>GEDCOM Writers</strong>
<ul>
<li>The requirements are the same as for Full Support described above.</li>
</ul>
</li>
</ul>
<h4>No Support</h4>
<p>Systems that cannot read or write documents encoded with UTF-8 should not attempt to support GEDCOM 5.5.2.</p>
</dd>
<dt id="cont-and-conc-change">CONT and CONC</dt>
<dd>
<p>In GEDCOM 5.5.2, the CONT and CONC subrecords are allowed with almost all records or subrecords that have a <a class="external" href="gedcom-5.5.2.html#line-value-component">line_value</a>. The exceptions are the HEAD.CHAR or HEAD.GEDC.VERS subrecords: CONT and CONC are not valid with those subrecords.</p>
<p>While CONT and CONC may appear in more places, that does not imply that line_values may be longer than stated in the specification or that line-ending characters are valid in line_values. All line_values must meet the specific requirements described for their subrecords.</p>
<h4>Full Support</h4>
<ul>
<li>
<strong>GEDCOM Readers</strong>
<ul>
<li>Implement CONT and CONC processing <em>prior</em> to evaluating the line_value in a <a class="external" href="gedcom-5.5.2.html#gedcom-line-syntax">gedcom_line</a> so that CONT and CONC can be used with any subrecord.</li>
<li>Validate the line_value <em>after</em> processing CONT and CONC subrecords.</li>
</ul>
</li>
<li>
<strong>GEDCOM Writers</strong>
<ul>
<li>Do not use a CONC subrecord when the line_value will not overflow the maximum length of a <a class="external" href="gedcom-5.5.2.html#gedcom-line-syntax">gedcom_line</a>.</li>
<li>Do not use a CONC subrecord with subrecords that have keyword line_values.</li>
</ul>
</li>
</ul>
<h4>Limited Support</h4>
<p>Systems that cannot support CONT and CONC with any subrecord will usually meet the requirements for limited support. This will be common for systems that support CONT and CONC in the typical contexts where they are used in GEDCOM 5.5 and 5.5.1, such as with the NOTE and ADDR subrecords.</p>
<ul>
<li>
<strong>GEDCOM Readers</strong>
<ul>
<li>When a CONT or CONC subrecord occurs in a context that is not supported, write an error message. This should be no different from the current behavior of systems that claim support for GEDCOM 5.5 or 5.5.1.</li>
</ul>
</li>
<li>
<strong>GEDCOM Writers</strong>
<ul>
<li>The requirements are the same as for Full Support described above.</li>
</ul>
</li>
</ul>
</dd>
<dt id="white-space-handling-change">White Space Handling</dt>
<dd>
<p>White space handling has been simplified and clarified in GEDCOM 5.5.2. Reading and writing systems must implement the rules described in the <a href="gedcom-5.5.2.html#space-handling">Space Handling</a> section of the specification.</p>
</dd>
<dt id="head-char-vers-change">HEAD.CHAR.VERS</dt>
<dd>
<p>HEAD.CHAR.VERS has been removed in GEDCOM 5.5.2. GEDCOM 5.5.2 uses the <strong>UTF-8</strong> character encoding exclusively and a useful version number does not apply to <strong>UTF-8</strong>.</p>
<ul>
<li>
<strong>GEDCOM Readers</strong>
<ul>
<li>If a HEAD.CHAR.VERS subrecord is present, ignore the subrecord and write an error message.</li>
</ul>
</li>
<li>
<strong>GEDCOM Writers</strong>
<ul>
<li>Do not write a HEAD.CHAR.VERS subrecord.</li>
</ul>
</li>
</ul>
</dd>
<dt id="head-dest-not-mandatory-change">HEAD.DEST</dt>
<dd>
<p>HEAD.DEST is <em>not</em> mandatory in GEDCOM 5.5.2 and its use is <a href="gedcom-5.5.2.html#sour-and-dest">discouraged</a>.</p>
<ul>
<li>
<strong>GEDCOM Readers</strong>
<ul>
<li>If a HEAD.DEST subrecord is present, ignore the subrecord.</li>
</ul>
</li>
<li>
<strong>GEDCOM Writers</strong>
<ul>
<li>Do not write a HEAD.DEST subrecord.</li>
</ul>
</li>
</ul>
</dd>
<dt id="fam-indi-subm-change">FAM.SUBM and INDI.SUBM</dt>
<dd>
<p>The FAM.SUBM and INDI.SUBM subrecords are not valid in GEDCOM 5.5.2.</p>
<ul>
<li>
<strong>GEDCOM Readers</strong>
<ul>
<li>If FAM.SUBM or INDI.SUBM subrecords are present, ignore the subrecords and write a single error message or an error message for each occurrence.</li>
</ul>
</li>
<li>
<strong>GEDCOM Writers</strong>
<ul>
<li>Do not write FAM.SUBM or INDI.SUBM subrecords.</li>
</ul>
</li>
</ul>
</dd>
<dt id="indi-even-event-descriptor-change">INDI.EVEN <EVENT_DESCRIPTOR></dt>
<dd>
<p>The INDI.EVEN subrecord in GEDCOM 5.5.2 includes an <<a href="gedcom-5.5.2.html#event-descriptor-pe">EVENT_DESCRIPTOR</a>> line_value.</p>
<ul>
<li>
<strong>GEDCOM Readers</strong>
<ul>
<li>Process the INDI.EVEN line_value in the same or similar manner as the application currently processes the FAM.EVEN line_value.</li>
</ul>
</li>
<li>
<strong>GEDCOM Writers</strong>
<ul>
<li>Allow end users to specify an INDI.EVEN line_value.</li>
<li>Write INDI.EVEN line_values when the end user has specified a value.</li>
</ul>
</li>
</ul>
</dd>
<dt id="indi-rfn-change">INDI.RFN</dt>
<dd>
<p>INDI.RFN has been removed in GEDCOM 5.5.2. The INDI.RFN subrecord in GEDCOM 5.5.1 and previous was intended to hold a PERMANENT_RECORD_FILE_NUMBER, a record number using a "registered network resource". The registration system was never implemented.</p>
<ul>
<li>
<strong>GEDCOM Readers</strong>
<ul>
<li>If an INDI.RFN subrecord is present, ignore the subrecord and write an error message.</li>
</ul>
</li>
<li>
<strong>GEDCOM Writers</strong>
<ul>
<li>Do not write an INDI.RFN subrecord.</li>
</ul>
</li>
</ul>
</dd>
<dt id="indi-lds-change">LDS Subrecords</dt>
<dd>
<p>Subrecords that were specific to The Church of Jesus Christ of Latter-day Saints have been removed from GEDCOM 5.5.2. This includes the following records and subrecords: AFN, ANCE, BAPL, CONL, DESC, ENDL, FAMF, ORDI, SLGC, SLGS, SUBN, TEMP.</p>
<p>For more information, see <a class="external" href="lds.html">Obsolete LDS Definitions</a>.</p>
<ul>
<li>
<strong>GEDCOM Readers</strong>
<ul>
<li>Ignore the subrecords listed above and issue error messages <em>or</em> convert the subrecords to the appropriate internal structures in the reading system.</li>
</ul>
</li>
<li>
<strong>GEDCOM Writers</strong>
<ul>
<li>Do not write the subrecords listed above.</li>
</ul>
</li>
</ul>
</dd>
<dt id="location-coordinate-change">MAP.LATI and MAP.LONG</dt>
<dd>
<p>The size of the MAP.LATI and MAP.LONG line_values have been changed in GEDCOM 5.5.2. The PLACE_LATITUDE size in GEDCOM 5.5.2 is "{Size=2:10}". The PLACE_LONGITUDE size in GEDCOM 5.5.2 is "{Size=2:11}".</p>
<ul>
<li>
<strong>GEDCOM Readers</strong>
<ul>
<li>Validate MAP.LATI and MAP.LONG line_values using the GEDCOM 5.5.2 size restrictions.</li>
</ul>
</li>
<li>
<strong>GEDCOM Writers</strong>
<ul>
<li>Write MAP.LATI and MAP.LONG line_values that meet GEDCOM 5.5.2 size restrictions.</li>
</ul>
</li>
</ul>
</dd>
<dt id="multimedia-file-reference-change">OBJE.FILE</dt>
<dd>
<p>The OBJE.FILE subrecord's <MULTIMEDIA_FILE_REFERENCE> line_value has been expanded from 30 characters in GEDCOM 5.5.1 to 1048 characters in GEDCOM 5.5.2.</p>
<ul>
<li>
<strong>GEDCOM Readers</strong>
<ul>
<li>Validate OBJE.FILE line_values using the GEDCOM 5.5.2 size restrictions.</li>
</ul>
</li>
<li>
<strong>GEDCOM Writers</strong>
<ul>
<li>Write OBJE.FILE line_values that meet GEDCOM 5.5.2 size restrictions.</li>
</ul>
</li>
</ul>
</dd>
<!-- TODO Write this entry if change is retained -->
<!--
<dt id="phon-email-fax-www-change">PHON, EMAIL, FAX, and WWW</dt>
<dd>
<p>text</p>
</dd>
-->
<dt id="system-id-change">APPROVED_SYSTEM_ID and RECEIVING_SYSTEM_NAME</dt>
<dd>
<p>The <APPROVED_SYSTEM_ID> and <RECEIVING_SYSTEM_NAME> primitive values in GEDCOM 5.5.1 have been merged as <<a href="gedcom-5.5.2.html#system-id-pe">SYSTEM_ID</a>> in GEDCOM 5.5.2, and its length has been expanded from 20 characters to 60 characters.</p>
<ul>
<li>
<strong>GEDCOM Readers</strong>
<ul>
<li>Validate HEAD.SOUR and HEAD.DEST line_values using the GEDCOM 5.5.2 size restrictions.</li>
</ul>
</li>
<li>
<strong>GEDCOM Writers</strong>
<ul>
<li>Write HEAD.SOUR and HEAD.DEST line_values that meet GEDCOM 5.5.2 size restrictions.</li>
</ul>
</li>
</ul>
</dd>
<dt id="valid-pointer-characters-change">Pointer Characters</dt>
<dd>
<p><strong>Valid Pointer Characters</strong> – Prior versions of GEDCOM allowed a wide range of characters in <a href="#id-component">ID</a> values. GEDCOM 5.5.2 restricts valid ID characters to a <a href="#id-character-classes">smaller subset of characters</a>.</p>
</dd>
</dl>
</section>
</article>
</body>
</html>