API Design for Manuscript Import

api.json

{
   "title":"Instructions for *ACL Proceedings", 
   "content":[
      {
         "type": "paragraph",
         "sentences": [ 
            {
               "type": "sentence",
               "text": "First Author"
            },
            {
               "type": "sentence",
               "text": "Affiliation / Address line 1"
            },
            {
               "type": "sentence",
               "text": "Affiliation / Address line 2"
            },
            {
               "type": "sentence",
               "text": "Affiliation / Address line 3"
            },
            {
               "type": "sentence",
               "text": "email@domain"
            },
         ]
      },
      {
         "type": "paragraph",
         "sentences": [ 
            {
               "type": "sentence",
               "text": "Second Author"
            },
            {
               "type": "sentence",
               "text": "Affiliation / Address line 1"
            },
            {
               "type": "sentence",
               "text": "Affiliation / Address line 2"
            },
            {
               "type": "sentence",
               "text": "Affiliation / Address line 3"
            },
            {
               "type": "sentence",
               "text": "email@domain"
            },
         ]
      },
      {
         "type": "paragraph",
         "sentences": [
            {
               "type": "sentence",
               "text": "Abstract"
            }
         ]
      },
      {
         "type": "paragraph",
         "sentences": [
            {
               "type": "sentence",
               "text": "This is an abstract. The text goes here"
            }
         ]
      },
      {
         "type": "paragraph",
         "sentences": [
            {
               "type": "sentence",
               "text": "1 Title of Section One"
            }
         ]
      },
      {
         "type": "paragraph",
         "sentences": [
            {
               "type": "sentence",
               "text": "I am a sentence that cite two papers, including"
            },
            {
               "type": "citation",
               "text": "(American Psychological Association, 1983)",
               "reference_index": 1
            },
            {
               "type": "sentence",
               "text": "and"
            },
             {
               "type": "citation",
               "text": "(Aho and Ullman, 1972)",
               "reference_index": 0
            },
            {
               "type": "sentence",
               "text": "."
            },
         ]
      },
      {
         "type": "paragraph",
         "sentences": [
            {
               "type": "sentence",
               "text": "2 Title of Section Two"
            }
         ]
      },
      {
         "type": "paragraph",
         "sentences": [
            {
               "type": "sentence",
               "text": "I am a sentence that cite one paper here"
            },
            {
               "type": "citation",
               "text": "(American Psychological Association, 1983)",
               "reference_index": 1
            },
            {
               "type": "sentence",
               "text": ", and I cite the same paper again"
            },
             {
               "type": "citation",
               "text": "(American Psychological Association, 1983)",
               "reference_index": 0
            },
            {
               "type": "sentence",
               "text": "within one sentence."
            },
         ]
      }
   ],
   "references":[
      {
         "..."
      },
      {
         "..."
      }
   ] 
}

Important notes:

• Title is a singular sentence, at the top of document, no need to define type.
• Section titles are a standalone paragraph with a single sentence.
• Paragraphs bundle text, hence the need to differentiate between types.
• Each citation will come with space before and after when serialized i.e inserted as " (American Psychological Association, 1983) ".
• Each citation needs a reference_index pointer i.e. references[reference_index]["title"] to get the title (pointers start from 0).
• Paragraphs are immediately followed by an empty line next.
• Appendix section can be ignored.

Remaining considerations:

• What happens if a paper is not in the database?
  • Are citations included?
  • Are citations not clickable?
  • Are they rendered just as text? with no metadata?

At the end:

We should check if further optimization / composition / properties clean up is needed.