מדריך כלי JSON: המרת מסמכים ונתונים ל-JSON ובחזרה

מדריך זה מסביר כיצד כלי ה-JSON קוראים וכותבים קבצים, את פורמט המסמך שבו PDF ל-JSON ו-Word ל-JSON פועלים, ואיזה כלי להשתמש בו לכל משימה.

מדוע JSON

JSON הוא פורמט הנתונים שתוכניות, שירותי אינטרנט ומודלי AI קוראים בקלות הרבה ביותר: אובייקטים עם שדות בעלי שם, רשימות, מספרים, טקסט, true, false ו-null, ולא יותר מזה. מסמכים וגיליונות אלקטרוניים לא נשמרים בצורה הזו. משפחת הכלים הזו מגשרת על הפער בשני הכיוונים: היא הופכת PDF, קובצי Word, גיליונות אלקטרוניים, CSV, YAML ו-XML ל-JSON, והיא הופכת JSON בחזרה לקבצים שאנשים קוראים, כגון PDF, Word, Excel, CSV ו-HTML.

כל כלי פועל על השרתים שלנו בחיבור מאובטח ומוחק את הקובץ שהועלה בתוך 60 דקות. אפשר להדביק קלט טקסטואלי ישירות במקום להעלות אותו.

איזה כלי לכל משימה

ל-Markdown יש זוג משלו: Markdown ל-JSON מייצא עץ מסמך ו-JSON ל-Markdown הופך JSON לתוכן עניינים או לטבלה של Markdown.

פורמט המסמך

PDF ל-JSON ו-Word ל-JSON כותבים את אותה צורה, כך שקטע קוד אחד מטפל בשניהם. לשורש יש תמיד את השדות הבאים:

{
  "format": "acepdfmd-document",
  "version": 1,
  "source": {"type": "pdf", "filename": "report.pdf", "title": "Q3 Report", "pages": 12},
  "pages": [{"number": 1, "width": 612, "height": 792, "words": 380, "text": "..."}],
  "blocks": [
    {"type": "heading", "level": 1, "text": "Q3 Report"},
    {"type": "paragraph", "text": "Revenue grew..."},
    {"type": "list", "ordered": false, "items": [{"level": 0, "text": "Europe"}]},
    {"type": "table", "header": ["Region", "Q3"], "rows": [["Europe", 1200.5]]}
  ],
  "tables": [{"index": 1, "page": 3, "rows": [["Region", "Q3"], ["Europe", 1200.5]]}],
  "form_fields": [{"name": "email", "type": "text", "value": "[email protected]"}],
  "extraction": {"engine": "pdf_to_markdown/layout", "mode": "structure", "ocr": false, "warnings": []}
}

השדות משמעותם כך:

• source: מה היה הקובץ, עם המטא-דאטה שנשא (כותרת, מחבר, נושא, מילות מפתח, תאריכי יצירה ושינוי, מספר עמודים). קובצי Word מוסיפים את מספר המילים, הטבלאות והתמונות.
• pages: רשומה אחת לכל עמוד PDF עם הגודל שלו בנקודות, הסיבוב שלו, ספירת מילים והטקסט שלו. לקובצי Word אין עמודים, כי Word מסדר עמודים רק בהדפסה.
• blocks: המסמך בסדר הקריאה. הסוגים הם heading (עם רמה 1 עד 6), paragraph (עם שם סטייל אופציונלי מ-Word), list (מסודר או לא, פריטים עם רמת קינון), table (כותרת ושורות מוקלדות), code, blockquote, rule ו-image.
• tables: לגבי PDF, כל טבלה שאותרה עם העמוד שבו נמצאה ובעבור טבלה שממשיכה, העמוד שבו היא מסתיימת. תאים שנראים כמספרים הם מספרים.
• form_fields: מופיע רק כשל-PDF יש טופס. לכל שדה יש שם, סוג (text, choice, button או signature) וערך נוכחי.
• extraction: איזה ממיר רץ, המצב שבחרת, אם היה צריך OCR, ואזהרות כלשהן, כגון טבלה שלא הייתה ניתנת לזיהוי.

גרסה 1 של הפורמט הזה רק מוסיפה שדות; שדות קיימים שומרים על השמות והמשמעות שלהם.

נתונים טבלאיים וקינון

CSV ו-Excel שטוחים, JSON לא. כש-JSON הופך ל-CSV או ל-Excel, אובייקטים מקוננים משוטחים לשמות עמודות עם נקודות ומערכים לשמות ממוספרים, כך שרשומת הזמנה עם אובייקט לקוח ומערך פריטים הופכת לעמודות כמו customer.name, items[0].sku ו-items[1].sku. כש-CSV או Excel חוזרים ל-JSON, כותרות שנכתבות באופן הזה נבנות מחדש לאובייקטים ומערכים מקוננים. כותרת עם נקודה רגילה בתוכה, כגון מספר גרסה או קיצור, נותרת ללא שינוי.

ערכים מוקלדים בכניסה: מספרים הופכים למספרים, true ו-false הופכים לבוליאנים, תא ריק הופך ל-null, וכל השאר נשאר מחרוזת. תאריכים שמגיעים מ-Excel נכתבים כמחרוזות ISO 8601, כי ל-JSON אין סוג תאריך. החלף את סוגי הערכים לטקסט כשמזהים עם אפסים מובילים חייבים להישאר בדיוק כפי שנכתבו.

אימות ותיקון

כל כלי JSON מאמת את הקלט שלו באותו אופן. קובץ לא תקין נדחה עם השורה והעמודה של הטעות הראשונה, וקטע קצר מהשורה הזו. מעצב JSON יכול גם לתקן את הטעויות שאנשים מדביקים הכי הרבה: הערות, פסיקים מיותרים, מחרוזות במירכאות בודדות, מפתחות בלי מירכאות, True, False ו-None באותיות רישיות, NaN ו-Infinity, וגדרות קוד מסביב לטקסט. כשבוצע תיקון, התוצאה מודיעה לך, כך שכלום לא משתנה בשקט מבלי שתדע.

פרטיות

קבצים שהועלו וטקסט שהודבק מעובדים על השרתים שלנו ונמחקים בתוך 60 דקות; ראה את מדריך הפרטיות לפרטים. כלום לא נשמר מעבר לזמן הזה וכלום לא משמש לשום מטרה אחרת.